Attachment 436186 Details for Bug 373145 – 0001-eclass-writing-add-Documenting-Eclasses-section-and-.patch

[patch] 0001-eclass-writing-add-Documenting-Eclasses-section-and-.patch

0001-eclass-writing-add-Documenting-Eclasses-section-and-.patch (text/plain), 4.14 KB, created by Michael Orlitzky on 2016-06-02 15:04:43 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Michael Orlitzky

Created: 2016-06-02 15:04:43 UTC

Size: 4.14 KB

patch

obsolete

>From 7319fe88e89603d970653fc7ef48e067964cea72 Mon Sep 17 00:00:00 2001
>From: Michael Orlitzky <mjo@gentoo.org>
>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:</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:
>+# &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>
> 
>@@ -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:
>+# &lt;required; blurb about this variable&gt;
>+# foo=&quot;&lt;default value&gt;&quot;
>+</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: &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>
> 
>-- 
>2.7.3
>

Actions: View | Diff

Attachments on bug 373145: 436186 | 436188 | 436190 | 436192 | 451901