From 06690997c78d1edecdd5fd53d31d39a6742a928e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=B6kt=C3=BCrk=20Y=C3=BCksek?= Date: Sat, 29 Oct 2016 20:29:31 -0400 Subject: [PATCH 1/2] devbook.xsl: add support for disabling word-wrapping for table items --- devbook.xsl | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/devbook.xsl b/devbook.xsl index dce6595..b678170 100644 --- a/devbook.xsl +++ b/devbook.xsl @@ -104,6 +104,10 @@ + + + + -- 2.7.3 From 5b7cfbad923a67b1b187aec17bcd500cb3c7e430 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=B6kt=C3=BCrk=20Y=C3=BCksek?= Date: Sat, 29 Oct 2016 20:33:15 -0400 Subject: [PATCH 2/2] eclass-writing: improve the eclass documentation sections Replace the eclass documentation text blobs from eclass-manpages with tables. Add a section for eclass function variables. --- eclass-writing/text.xml | 469 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 417 insertions(+), 52 deletions(-) diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml index 9329d88..c759849 100644 --- a/eclass-writing/text.xml +++ b/eclass-writing/text.xml @@ -125,19 +125,16 @@ adhere to the following process:

-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. +Eclasses are documented with comment blocks which follow a special +markup syntax. The comment blocks are separated by empty new lines and +each block documents an individual entity of an eclass.

-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. +Documentation tags for various eclass elements are explained in their +respective sections below. Common to all the tags which accept +multiline freetext, the @CODE tag should be used when necessary +to create unformatted code chunks (such as example code) by placing +the tag at the beginning and the end.

@@ -157,26 +154,135 @@ 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. The format supported by -app-portage/eclass-manpages is as follows: +other relevant documentation. Eclass documentation block should be the +first documentation block to appear in the eclass. The following table +summarizes the available documentation tags:

- -# @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> - + + + + + + + + + + @ECLASS: + + + NO + + + Name of the eclass being documented. + + + Documents various information about the eclass. Must appear as the + first tag in the comment block. + + + + + @MAINTAINER: + + + NO + + + One or more name and email pairs. + + + List of maintainers for the eclass to be contacted. One line per + maintainer. Must start on a newline after the tag. + + + + + @AUTHOR: + + + YES + + + One or more name and email pairs. + + + List of authors for the eclass. One line per author. Must start on + a newline after the tag. + + + + + @BUGREPORTS: + + + YES + + + Multiline freetext. + + + Describes how bugs related to this eclass should be reported. + + + + + @VCSURL: + + + YES + + + A URI string. + + + Points to the URL of the VCS which contains the eclass source. + + + + + @BLURB: + + + NO + + + Single line freetext. + + + Contains a short description for the eclass. Must be on the same + line with the tag. + + + + + @DESCRIPTION: + + + YES + + + Multiline freetext. + + + Long description for the eclass. + + + + + @EXAMPLE: + + + YES + + + Multiline freetext. + + + Examples which illustrate various uses of this eclass. + + +
tagoptional?argumentsdescription
@@ -190,21 +296,95 @@ 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, +variable in your eclass. The tags available for documenting eclass +variables are as follows:

- -# @ECLASS-VARIABLE: foo -# [@DEFAULT_UNSET] -# [@INTERNAL] -# [@REQUIRED] -# @DESCRIPTION: -# <required; blurb about this variable> -# foo="<default value>" - + + + + + + + + + + @ECLASS-VARIABLE: + + + NO + + + Name of the eclass variable to which the documentation applies. + + + This tag applies to eclass specific variables that affect the + default behavior of the eclass. Read-only variables, which are + exported by the eclass for developer use, are also documented with + this tag. Must appear as the first tag in the comment block. + + + + + @DEFAULT_UNSET + + + YES + + + + + + Indicates that this variable is unset by default if not set by the + developer. + + + + + @INTERNAL + + + YES + + + + + + Indicates that the variable is internal to the eclass. + + + + + @REQUIRED + + + YES + + + + + + Indicates that this variable must be set by the developer. + + + + + @DESCRIPTION: + + + NO + + + Multiline freetext. + + + Long description for the eclass variable. + + +
tagoptional?argumentsdescription
@@ -217,22 +397,207 @@ variable in your eclass. The standard format supported by 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, +every function in your eclass. The standard tags available for +documentation are:

- -# @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> - + + + + + + + + + + @FUNCTION: + + + NO + + + Name of the function to which the documentation block applies. + + + Documents information about an eclass function such as its calling + convention etc. Must appear as the first tag in the comment block. + + + + + @USAGE: + + + NO + + + List of required and optional arguments to the function. + + + List of arguments that the eclass function accepts, specified in + the following syntax: <Required arguments> + [Optional arguments] + + + + + @RETURN: + + + * + + + Return value of the function. + + +

Description for the value returned by the function.

+

*: Not optional for functions that return a value.

+ + + + + @MAINTAINER: + + + YES + + + Multiline freetext. + + + List of contacts for the eclass function. One line per + maintainer. Must start on a newline after the tag. + + + + + @INTERNAL + + + YES + + + + + + Indicates that the function is internal to the eclass and should + not be called from outside. + + + + + @DESCRIPTION: + + + * + + + Multiline freetext. + + +

Long description for the eclass function.

+

*: Not optional if RETURN: is absent.

+ + +
tagoptional?argumentsdescription
+ + + +
+Eclass Function Variables + + +

+Eclass functions may make use of variables just like any other bash +function. Special function-specific variables should be documented +using the following tags: +

+ + + + + + + + + + + @VARIABLE: + + + NO + + + Name of the function-specific variable to which the documentation applies. + + + This tag applies to variables consumed by specific functions of + the eclass. They are in effect only when the specific function is + called. + + + + + @DEFAULT_UNSET + + + YES + + + + + + Indicates that this variable is unset by default if not set by the + developer. + + + + + @INTERNAL + + + YES + + + + + + Indicates that the variable is internal to the eclass function. + + + + + @REQUIRED + + + YES + + + + + + Indicates that this variable must be set by the developer. + + + + + @DESCRIPTION: + + + NO + + + Multiline freetext. + + + Long description for the function variable. + + +
tagoptional?argumentsdescription
+
-- 2.7.3