From 7319fe88e89603d970653fc7ef48e067964cea72 Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Thu, 2 Jun 2016 10:31:56 -0400 Subject: [PATCH 1/4] 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:

+Documenting Eclasses + + +

+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 app-portage/eclass-manpages package +processes these headers to create documentation for the eclass. The +result can be seen in our eclass +reference, or by installing app-portage/eclass-manpages. +

+

+The format for eclass, variable, and function headers are described +below. Before committing your eclass, please ensure that the +eclass-to-manpage.sh script (currently in $FILESDIR for +app-portage/eclass-manpages in the gentoo.git repo) does +not report any errors or serious warnings for your eclass. +

+ +
+ + +
Basic Eclass Format @@ -132,11 +155,29 @@ underscores and dots. Eclasses are not intrinsically versioned.

-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 +app-portage/eclass-manpages is as follows:

+ +# @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> + +
@@ -149,6 +190,21 @@ Top level variables may be defined as for ebuilds. If any USE flags are used, IUSE must be set. The KEYWORDS variable must not be set in an eclass.

+

+You should document the meaning, usage, and default value of every +variable in your eclass. The standard format supported by +app-portage/eclass-manpages is, +

+ + +# @ECLASS-VARIABLE: foo +# [@DEFAULT_UNSET] +# [@INTERNAL] +# [@REQUIRED] +# @DESCRIPTION: +# <required; blurb about this variable> +# foo="<default value>" + @@ -161,7 +217,22 @@ eclass. Eclasses may define functions. These functions will be visible to anything which inherits the eclass.

+

+You should document the purpose, arguments, usage, and return value of +every function in your eclass. The standard format supported by +app-portage/eclass-manpages is, +

+ +# @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> + -- 2.7.3