From 7319fe88e89603d970653fc7ef48e067964cea72 Mon Sep 17 00:00:00 2001
From: Michael Orlitzky
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:
+Documenting Eclasses
+
+
+
+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.
+
+
+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.
+
+
+
+
+
+
Basic Eclass Format
@@ -132,11 +155,29 @@ 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.
+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:
+
+# @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>
+
+
@@ -149,6 +190,21 @@ 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,
+
+
+
+# @ECLASS-VARIABLE: foo
+# [@DEFAULT_UNSET]
+# [@INTERNAL]
+# [@REQUIRED]
+# @DESCRIPTION:
+# <required; blurb about this variable>
+# foo="<default value>"
+