From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path:
Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80])
(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
(No client certificate requested)
by finch.gentoo.org (Postfix) with ESMTPS id E2F721395E2
for ; Mon, 31 Oct 2016 01:21:50 +0000 (UTC)
Received: from pigeon.gentoo.org (localhost [127.0.0.1])
by pigeon.gentoo.org (Postfix) with SMTP id 7AAEFE0C03;
Mon, 31 Oct 2016 01:21:49 +0000 (UTC)
Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183])
(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
(No client certificate requested)
by pigeon.gentoo.org (Postfix) with ESMTPS id 4807FE0C03
for ; Mon, 31 Oct 2016 01:21:49 +0000 (UTC)
Received: from oystercatcher.gentoo.org (unknown [IPv6:2a01:4f8:202:4333:225:90ff:fed9:fc84])
(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
(No client certificate requested)
by smtp.gentoo.org (Postfix) with ESMTPS id DC63A340F43
for ; Mon, 31 Oct 2016 01:21:47 +0000 (UTC)
Received: from localhost.localdomain (localhost [127.0.0.1])
by oystercatcher.gentoo.org (Postfix) with ESMTP id 0F34A249C
for ; Mon, 31 Oct 2016 01:21:46 +0000 (UTC)
From: "Göktürk Yüksek"
To: gentoo-commits@lists.gentoo.org
Content-Transfer-Encoding: 8bit
Content-type: text/plain; charset=UTF-8
Reply-To: gentoo-dev@lists.gentoo.org, "Göktürk Yüksek"
Message-ID: <1477876153.092cc15adaf3afa8b5ad0f5af78d1eafd1ea5840.gokturk@gentoo>
Subject: [gentoo-commits] proj/devmanual:master commit in: eclass-writing/
X-VCS-Repository: proj/devmanual
X-VCS-Files: eclass-writing/text.xml
X-VCS-Directories: eclass-writing/
X-VCS-Committer: gokturk
X-VCS-Committer-Name: Göktürk Yüksek
X-VCS-Revision: 092cc15adaf3afa8b5ad0f5af78d1eafd1ea5840
X-VCS-Branch: master
Date: Mon, 31 Oct 2016 01:21:46 +0000 (UTC)
Precedence: bulk
List-Post:
List-Help:
List-Unsubscribe:
List-Subscribe:
List-Id: Gentoo Linux mail
X-BeenThere: gentoo-commits@lists.gentoo.org
X-Archives-Salt: c0c9d33d-18dd-4b1b-a269-82fa0b112307
X-Archives-Hash: b456652d333a885833401ee35dc9eeb5
commit: 092cc15adaf3afa8b5ad0f5af78d1eafd1ea5840
Author: Michael Orlitzky gentoo org>
AuthorDate: Thu Jun 2 14:31:56 2016 +0000
Commit: Göktürk Yüksek gentoo 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:
+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>"
+