diff options
| author |   Michael Orlitzky <mjo@gentoo.org> | 2016-06-02 10:31:56 -0400 |
|---|---|---|
| committer |   Göktürk Yüksek <gokturk@gentoo.org> | 2016-10-30 21:09:13 -0400 |
| commit | 092cc15adaf3afa8b5ad0f5af78d1eafd1ea5840 (patch) | |
| tree | 46aed1e60c24e21710ee192d7d242b83b85b879b /eclass-writing | |
| parent | tools-reference/find: encourage the while read loop with '-print0' (diff) | |
| download | devmanual-092cc15adaf3afa8b5ad0f5af78d1eafd1ea5840.tar.gz devmanual-092cc15adaf3afa8b5ad0f5af78d1eafd1ea5840.tar.bz2 devmanual-092cc15adaf3afa8b5ad0f5af78d1eafd1ea5840.zip | |
eclass-writing: add "Documenting Eclasses" section and examples.
There is no mention of the standard eclass documentation headers on
the eclass-writing page. This commit adds a new section titled
"Documenting Eclasses", and adds examples of the three main types of
headers for eclasses, functions, and variables.
Gentoo-Bug: 373145
Diffstat (limited to 'eclass-writing')
| -rw-r--r-- | eclass-writing/text.xml | 77 |
1 files changed, 74 insertions, 3 deletions
diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml index 1a115b1..488230d 100644 --- a/eclass-writing/text.xml +++ b/eclass-writing/text.xml @@ -121,6 +121,29 @@ adhere to the following process:</p> </section> <section> +<title>Documenting Eclasses</title> +<body> + +<p> +Eclasses are documented as any other bash project is, with code +comments. We do however have a standard format for eclass, variable, +and function headers. The <c>app-portage/eclass-manpages</c> package +processes these headers to create documentation for the eclass. The +result can be seen in our <uri link="::eclass-reference/">eclass +reference</uri>, or by installing <c>app-portage/eclass-manpages</c>. +</p> +<p> +The format for eclass, variable, and function headers are described +below. Before committing your eclass, please ensure that the +<c>eclass-to-manpage.sh</c> script (currently in <c>$FILESDIR</c> for +<c>app-portage/eclass-manpages</c> in the <c>gentoo.git</c> repo) does +not report any errors or serious warnings for your eclass. +</p> +</body> +</section> + + +<section> <title>Basic Eclass Format</title> <body> @@ -132,11 +155,29 @@ underscores and dots. Eclasses are not intrinsically versioned. </p> <p> -Eclasses should start with the standard ebuild header, along with comments -explaining the maintainer and purpose of the eclass, and any other relevant -documentation. +Eclasses should start with the standard ebuild header, along with +comments explaining the maintainer and purpose of the eclass, and any +other relevant documentation. The format supported by +<c>app-portage/eclass-manpages</c> is as follows: </p> +<codesample lang="ebuild"> +# @ECLASS: foo.eclass +# @MAINTAINER: +# <required; list of contacts, one per line> +# @AUTHOR: +# <optional; list of authors, one per line> +# @BUGREPORTS: +# <optional; description of how to report bugs; +# default: tell people to use bugs.gentoo.org> +# @VCSURL: <optional; url to vcs for this eclass; default: https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/@ECLASS@> +# @BLURB: <required; short description> +# @DESCRIPTION: +# <optional; long description> +# @EXAMPLE: +# <optional; example usage> +</codesample> + </body> </section> @@ -149,6 +190,21 @@ Top level variables may be defined as for ebuilds. If any USE flags are used, <c>IUSE</c> must be set. The <c>KEYWORDS</c> variable must <b>not</b> be set in an eclass. </p> +<p> +You should document the meaning, usage, and default value of every +variable in your eclass. The standard format supported by +<c>app-portage/eclass-manpages</c> is, +</p> + +<codesample lang="ebuild"> +# @ECLASS-VARIABLE: foo +# [@DEFAULT_UNSET] +# [@INTERNAL] +# [@REQUIRED] +# @DESCRIPTION: +# <required; blurb about this variable> +# foo="<default value>" +</codesample> </body> </section> @@ -161,7 +217,22 @@ eclass. Eclasses may define functions. These functions will be visible to anything which inherits the eclass. </p> +<p> +You should document the purpose, arguments, usage, and return value of +every function in your eclass. The standard format supported by +<c>app-portage/eclass-manpages</c> is, +</p> +<codesample lang="ebuild"> +# @FUNCTION: foo +# @USAGE: <required arguments to foo> [optional arguments to foo] +# @RETURN: <whatever foo returns> +# @MAINTAINER: +# <optional; list of contacts, one per line> +# [@INTERNAL] +# @DESCRIPTION: +# <required if no @RETURN; blurb about this function> +</codesample> </body> </section> |