Attachment #436186 for bug #373145




</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>


</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. The format supported by
<c>app-portage/eclass-manpages</c> is as follows:
</p>

<codesample lang="ebuild">
# @ECLASS: foo.eclass
# @MAINTAINER:
# &lt;required; list of contacts, one per line&gt;
# @AUTHOR:
# &lt;optional; list of authors, one per line&gt;
# @BUGREPORTS:
# &lt;optional; description of how to report bugs;
#  default: tell people to use bugs.gentoo.org&gt;
# @VCSURL: &lt;optional; url to vcs for this eclass; default: https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/@ECLASS@&gt;
# @BLURB: &lt;required; short description&gt;
# @DESCRIPTION:
# &lt;optional; long description&gt;
# @EXAMPLE:
# &lt;optional; example usage&gt;
</codesample>

</body>
</section>


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:
# &lt;required; blurb about this variable&gt;
# foo=&quot;&lt;default value&gt;&quot;
</codesample>

</body>
</section>

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: &lt;required arguments to foo&gt; [optional arguments to foo]
# @RETURN: &lt;whatever foo returns&gt;
# @MAINTAINER:
# &lt;optional; list of contacts, one per line&gt;
# [@INTERNAL]
# @DESCRIPTION:
# &lt;required if no @RETURN; blurb about this function&gt;
</codesample>
</body>
</section>

- 

Return to bug 373145

Lines 121-126 adhere to the following process:</p> Link Here

(-)a/eclass-writing/text.xml (-4 / +74 lines)
121	</section>	121	</section>
122		122
123	<section>	123	<section>
		124	<title>Documenting Eclasses</title>
		125	<body>
		126
		127	<p>
		128	Eclasses are documented as any other bash project is, with code
		129	comments. We do however have a standard format for eclass, variable,
		130	and function headers. The <c>app-portage/eclass-manpages</c> package
		131	processes these headers to create documentation for the eclass. The
		132	result can be seen in our <uri link="::eclass-reference/">eclass
		133	reference</uri>, or by installing <c>app-portage/eclass-manpages</c>.
		134	</p>
		135	<p>
		136	The format for eclass, variable, and function headers are described
		137	below. Before committing your eclass, please ensure that the
		138	<c>eclass-to-manpage.sh</c> script (currently in <c>$FILESDIR</c> for
		139	<c>app-portage/eclass-manpages</c> in the <c>gentoo.git</c> repo) does
		140	not report any errors or serious warnings for your eclass.
		141	</p>
		142	</body>
		143	</section>
		144
		145
		146	<section>
124	<title>Basic Eclass Format</title>	147	<title>Basic Eclass Format</title>
125	<body>	148	<body>
126		149
Lines 132-142 underscores and dots. Eclasses are not intrinsically versioned. Link Here
132	</p>	155	</p>
133		156
134	<p>	157	<p>
135	Eclasses should start with the standard ebuild header, along with comments	158	Eclasses should start with the standard ebuild header, along with
136	explaining the maintainer and purpose of the eclass, and any other relevant	159	comments explaining the maintainer and purpose of the eclass, and any
137	documentation.	160	other relevant documentation. The format supported by
		161	<c>app-portage/eclass-manpages</c> is as follows:
138	</p>	162	</p>
139		163
		164	<codesample lang="ebuild">
		165	# @ECLASS: foo.eclass
		166	# @MAINTAINER:
		167	# <required; list of contacts, one per line>
		168	# @AUTHOR:
		169	# <optional; list of authors, one per line>
		170	# @BUGREPORTS:
		171	# <optional; description of how to report bugs;
		172	# default: tell people to use bugs.gentoo.org>
		173	# @VCSURL: <optional; url to vcs for this eclass; default: https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/@ECLASS@>
		174	# @BLURB: <required; short description>
		175	# @DESCRIPTION:
		176	# <optional; long description>
		177	# @EXAMPLE:
		178	# <optional; example usage>
		179	</codesample>
		180
140	</body>	181	</body>
141	</section>	182	</section>
142		183
Lines 149-154 Top level variables may be defined as for ebuilds. If any USE flags are Link Here
149	used, <c>IUSE</c> must be set. The <c>KEYWORDS</c> variable must <b>not</b> be set in an	190	used, <c>IUSE</c> must be set. The <c>KEYWORDS</c> variable must <b>not</b> be set in an
150	eclass.	191	eclass.
151	</p>	192	</p>
		193	<p>
		194	You should document the meaning, usage, and default value of every
		195	variable in your eclass. The standard format supported by
		196	<c>app-portage/eclass-manpages</c> is,
		197	</p>
		198
		199	<codesample lang="ebuild">
		200	# @ECLASS-VARIABLE: foo
		201	# [@DEFAULT_UNSET]
		202	# [@INTERNAL]
		203	# [@REQUIRED]
		204	# @DESCRIPTION:
		205	# <required; blurb about this variable>
		206	# foo="<default value>"
		207	</codesample>
152		208
153	</body>	209	</body>
154	</section>	210	</section>
Lines 161-167 eclass. Link Here
161	Eclasses may define functions. These functions will be visible to anything which	217	Eclasses may define functions. These functions will be visible to anything which
162	inherits the eclass.	218	inherits the eclass.
163	</p>	219	</p>
		220	<p>
		221	You should document the purpose, arguments, usage, and return value of
		222	every function in your eclass. The standard format supported by
		223	<c>app-portage/eclass-manpages</c> is,
		224	</p>
164		225
		226	<codesample lang="ebuild">
		227	# @FUNCTION: foo
		228	# @USAGE: <required arguments to foo> [optional arguments to foo]
		229	# @RETURN: <whatever foo returns>
		230	# @MAINTAINER:
		231	# <optional; list of contacts, one per line>
		232	# [@INTERNAL]
		233	# @DESCRIPTION:
		234	# <required if no @RETURN; blurb about this function>
		235	</codesample>
165	</body>	236	</body>
166	</section>	237	</section>
167		238
168	-