public inbox for gentoo-commits@lists.gentoo.org
 help / color / mirror / Atom feed
From: "Göktürk Yüksek" <gokturk@gentoo.org>
To: gentoo-commits@lists.gentoo.org
Subject: [gentoo-commits] proj/devmanual:master commit in: eclass-writing/
Date: Mon, 31 Oct 2016 01:21:46 +0000 (UTC)	[thread overview]
Message-ID: <1477876153.092cc15adaf3afa8b5ad0f5af78d1eafd1ea5840.gokturk@gentoo> (raw)

commit:     092cc15adaf3afa8b5ad0f5af78d1eafd1ea5840
Author:     Michael Orlitzky <mjo <AT> gentoo <DOT> org>
AuthorDate: Thu Jun  2 14:31:56 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Mon Oct 31 01:09:13 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=092cc15a

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>
 


             reply	other threads:[~2016-10-31  1:21 UTC|newest]

Thread overview: 47+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2016-10-31  1:21 Göktürk Yüksek [this message]
  -- strict thread matches above, loose matches on Subject: below --
2024-04-29  6:31 [gentoo-commits] proj/devmanual:master commit in: eclass-writing/ Ulrich Müller
2024-04-29  6:31 Ulrich Müller
2024-04-29  6:31 Ulrich Müller
2024-04-29  6:31 Ulrich Müller
2024-01-19 21:06 Ulrich Müller
2023-08-26  5:30 Ulrich Müller
2023-05-27 18:49 Ulrich Müller
2022-04-30 17:01 Ulrich Müller
2022-04-28  8:12 Ulrich Müller
2022-04-24 12:52 Ulrich Müller
2022-03-26 16:16 Ulrich Müller
2022-03-23 14:10 Ulrich Müller
2022-03-20 13:48 Ulrich Müller
2022-03-18 18:10 Sam James
2022-03-18 18:10 Sam James
2022-03-16 14:47 Sam James
2022-03-16 14:47 Sam James
2021-12-09  5:01 Sam James
2021-10-13 13:44 Ulrich Müller
2021-09-04 10:38 Ulrich Müller
2021-09-04 10:36 Ulrich Müller
2021-09-04 10:36 Ulrich Müller
2021-09-04 10:33 Ulrich Müller
2021-09-04 10:33 Ulrich Müller
2021-04-07 17:35 Ulrich Müller
2021-03-30  6:55 Ulrich Müller
2021-03-30  6:55 Ulrich Müller
2021-03-30  6:55 Ulrich Müller
2021-03-30  6:55 Ulrich Müller
2021-03-30  6:55 Ulrich Müller
2021-03-30  6:55 Ulrich Müller
2021-03-30  6:55 Ulrich Müller
2021-03-30  6:55 Ulrich Müller
2021-03-30  6:55 Ulrich Müller
2021-03-30  6:55 Ulrich Müller
2021-03-30  6:55 Ulrich Müller
2020-12-29 22:08 Göktürk Yüksek
2020-09-18  7:01 Ulrich Müller
2019-09-20 22:52 Göktürk Yüksek
2019-08-30 15:51 Göktürk Yüksek
2019-08-30 15:51 Göktürk Yüksek
2016-10-31  1:21 Göktürk Yüksek
2016-10-31  1:21 Göktürk Yüksek
2016-10-31  1:21 Göktürk Yüksek
2016-10-31  1:21 Göktürk Yüksek
2011-12-13 20:17 Petteri Räty

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=1477876153.092cc15adaf3afa8b5ad0f5af78d1eafd1ea5840.gokturk@gentoo \
    --to=gokturk@gentoo.org \
    --cc=gentoo-commits@lists.gentoo.org \
    --cc=gentoo-dev@lists.gentoo.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox