commit: 092cc15adaf3afa8b5ad0f5af78d1eafd1ea5840 Author: Michael Orlitzky <mjo <AT> gentoo <DOT> org> AuthorDate: Thu Jun 2 14:31:56 2016 +0000 Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org> CommitDate: Mon Oct 31 01:09:13 2016 +0000 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=092cc15a
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 eclass-writing/text.xml | 77 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file 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>
