| 1 |
commit: 092cc15adaf3afa8b5ad0f5af78d1eafd1ea5840 |
| 2 |
Author: Michael Orlitzky <mjo <AT> gentoo <DOT> org> |
| 3 |
AuthorDate: Thu Jun 2 14:31:56 2016 +0000 |
| 4 |
Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org> |
| 5 |
CommitDate: Mon Oct 31 01:09:13 2016 +0000 |
| 6 |
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=092cc15a |
| 7 |
|
| 8 |
eclass-writing: add "Documenting Eclasses" section and examples. |
| 9 |
|
| 10 |
There is no mention of the standard eclass documentation headers on |
| 11 |
the eclass-writing page. This commit adds a new section titled |
| 12 |
"Documenting Eclasses", and adds examples of the three main types of |
| 13 |
headers for eclasses, functions, and variables. |
| 14 |
|
| 15 |
Gentoo-Bug: 373145 |
| 16 |
|
| 17 |
eclass-writing/text.xml | 77 +++++++++++++++++++++++++++++++++++++++++++++++-- |
| 18 |
1 file changed, 74 insertions(+), 3 deletions(-) |
| 19 |
|
| 20 |
diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml |
| 21 |
index 1a115b1..488230d 100644 |
| 22 |
--- a/eclass-writing/text.xml |
| 23 |
+++ b/eclass-writing/text.xml |
| 24 |
@@ -121,6 +121,29 @@ adhere to the following process:</p> |
| 25 |
</section> |
| 26 |
|
| 27 |
<section> |
| 28 |
+<title>Documenting Eclasses</title> |
| 29 |
+<body> |
| 30 |
+ |
| 31 |
+<p> |
| 32 |
+Eclasses are documented as any other bash project is, with code |
| 33 |
+comments. We do however have a standard format for eclass, variable, |
| 34 |
+and function headers. The <c>app-portage/eclass-manpages</c> package |
| 35 |
+processes these headers to create documentation for the eclass. The |
| 36 |
+result can be seen in our <uri link="::eclass-reference/">eclass |
| 37 |
+reference</uri>, or by installing <c>app-portage/eclass-manpages</c>. |
| 38 |
+</p> |
| 39 |
+<p> |
| 40 |
+The format for eclass, variable, and function headers are described |
| 41 |
+below. Before committing your eclass, please ensure that the |
| 42 |
+<c>eclass-to-manpage.sh</c> script (currently in <c>$FILESDIR</c> for |
| 43 |
+<c>app-portage/eclass-manpages</c> in the <c>gentoo.git</c> repo) does |
| 44 |
+not report any errors or serious warnings for your eclass. |
| 45 |
+</p> |
| 46 |
+</body> |
| 47 |
+</section> |
| 48 |
+ |
| 49 |
+ |
| 50 |
+<section> |
| 51 |
<title>Basic Eclass Format</title> |
| 52 |
<body> |
| 53 |
|
| 54 |
@@ -132,11 +155,29 @@ underscores and dots. Eclasses are not intrinsically versioned. |
| 55 |
</p> |
| 56 |
|
| 57 |
<p> |
| 58 |
-Eclasses should start with the standard ebuild header, along with comments |
| 59 |
-explaining the maintainer and purpose of the eclass, and any other relevant |
| 60 |
-documentation. |
| 61 |
+Eclasses should start with the standard ebuild header, along with |
| 62 |
+comments explaining the maintainer and purpose of the eclass, and any |
| 63 |
+other relevant documentation. The format supported by |
| 64 |
+<c>app-portage/eclass-manpages</c> is as follows: |
| 65 |
</p> |
| 66 |
|
| 67 |
+<codesample lang="ebuild"> |
| 68 |
+# @ECLASS: foo.eclass |
| 69 |
+# @MAINTAINER: |
| 70 |
+# <required; list of contacts, one per line> |
| 71 |
+# @AUTHOR: |
| 72 |
+# <optional; list of authors, one per line> |
| 73 |
+# @BUGREPORTS: |
| 74 |
+# <optional; description of how to report bugs; |
| 75 |
+# default: tell people to use bugs.gentoo.org> |
| 76 |
+# @VCSURL: <optional; url to vcs for this eclass; default: https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/@ECLASS@> |
| 77 |
+# @BLURB: <required; short description> |
| 78 |
+# @DESCRIPTION: |
| 79 |
+# <optional; long description> |
| 80 |
+# @EXAMPLE: |
| 81 |
+# <optional; example usage> |
| 82 |
+</codesample> |
| 83 |
+ |
| 84 |
</body> |
| 85 |
</section> |
| 86 |
|
| 87 |
@@ -149,6 +190,21 @@ Top level variables may be defined as for ebuilds. If any USE flags are |
| 88 |
used, <c>IUSE</c> must be set. The <c>KEYWORDS</c> variable must <b>not</b> be set in an |
| 89 |
eclass. |
| 90 |
</p> |
| 91 |
+<p> |
| 92 |
+You should document the meaning, usage, and default value of every |
| 93 |
+variable in your eclass. The standard format supported by |
| 94 |
+<c>app-portage/eclass-manpages</c> is, |
| 95 |
+</p> |
| 96 |
+ |
| 97 |
+<codesample lang="ebuild"> |
| 98 |
+# @ECLASS-VARIABLE: foo |
| 99 |
+# [@DEFAULT_UNSET] |
| 100 |
+# [@INTERNAL] |
| 101 |
+# [@REQUIRED] |
| 102 |
+# @DESCRIPTION: |
| 103 |
+# <required; blurb about this variable> |
| 104 |
+# foo="<default value>" |
| 105 |
+</codesample> |
| 106 |
|
| 107 |
</body> |
| 108 |
</section> |
| 109 |
@@ -161,7 +217,22 @@ eclass. |
| 110 |
Eclasses may define functions. These functions will be visible to anything which |
| 111 |
inherits the eclass. |
| 112 |
</p> |
| 113 |
+<p> |
| 114 |
+You should document the purpose, arguments, usage, and return value of |
| 115 |
+every function in your eclass. The standard format supported by |
| 116 |
+<c>app-portage/eclass-manpages</c> is, |
| 117 |
+</p> |
| 118 |
|
| 119 |
+<codesample lang="ebuild"> |
| 120 |
+# @FUNCTION: foo |
| 121 |
+# @USAGE: <required arguments to foo> [optional arguments to foo] |
| 122 |
+# @RETURN: <whatever foo returns> |
| 123 |
+# @MAINTAINER: |
| 124 |
+# <optional; list of contacts, one per line> |
| 125 |
+# [@INTERNAL] |
| 126 |
+# @DESCRIPTION: |
| 127 |
+# <required if no @RETURN; blurb about this function> |
| 128 |
+</codesample> |
| 129 |
</body> |
| 130 |
</section> |
Archives