commit: 3dfa91c478c62400e5849158679bb2e91db7d4da
Author: Thomas Bracht Laumann Jespersen <t <AT> laumann <DOT> xyz>
AuthorDate: Fri Mar 18 19:54:32 2022 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sun Mar 20 13:46:52 2022 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=3dfa91c4
eclass-writing: Use "required" instead of "not optional"
When figuring out if a documentation tag is required, the reader must
mentally handle "not optional" as "required". Simplify by changing the
"optional?" column to "required?".
Let us also stop shouting at the reader, so change "YES" and "NO" to
"Yes" and "No".
Signed-off-by: Thomas Bracht Laumann Jespersen <t <AT> laumann.xyz>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
eclass-writing/text.xml | 82 ++++++++++++++++++++++++-------------------------
1 file changed, 41 insertions(+), 41 deletions(-)
diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 0e6ca99..795ccd0 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -197,13 +197,13 @@ summarizes the available documentation tags:
<table>
<tr>
<th>tag</th>
- <th>optional?</th>
+ <th>required?</th>
<th>arguments</th>
<th>description</th>
</tr>
<tr>
<ti><c>@ECLASS:</c></ti>
- <ti>NO</ti>
+ <ti>Yes</ti>
<ti>Name of the eclass being documented</ti>
<ti>
Documents various information about the eclass. Must appear as the
@@ -212,7 +212,7 @@ summarizes the available documentation tags:
</tr>
<tr>
<ti><c>@MAINTAINER:</c></ti>
- <ti>NO</ti>
+ <ti>Yes</ti>
<ti>One or more name and email pairs</ti>
<ti>
List of maintainers for the eclass to be contacted. One line per
@@ -221,7 +221,7 @@ summarizes the available documentation tags:
</tr>
<tr>
<ti><c>@AUTHOR:</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti>One or more name and email pairs</ti>
<ti>
List of authors for the eclass. One line per author. Must start on
@@ -230,25 +230,25 @@ summarizes the available documentation tags:
</tr>
<tr>
<ti><c>@BUGREPORTS:</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti>Multiline freetext</ti>
<ti>Describes how bugs related to this eclass should be reported</ti>
</tr>
<tr>
<ti><c>@VCSURL:</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti>A URI string</ti>
<ti>Points to the URL of the VCS that contains the eclass source</ti>
</tr>
<tr>
<ti nowrap="nowrap"><c>@SUPPORTED_EAPIS:</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti>Space-separated list of EAPIs</ti>
<ti>List of EAPIs supported by this eclass</ti>
</tr>
<tr>
<ti><c>@PROVIDES:</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti>Space-separated list of eclass names</ti>
<ti>
List of indirectly inherited eclasses whose functions and variables may be
@@ -257,7 +257,7 @@ summarizes the available documentation tags:
</tr>
<tr>
<ti><c>@BLURB:</c></ti>
- <ti>NO</ti>
+ <ti>Yes</ti>
<ti>Single line freetext</ti>
<ti>
Contains a short description for the eclass. Must be on the same
@@ -266,19 +266,19 @@ summarizes the available documentation tags:
</tr>
<tr>
<ti><c>@DEPRECATED:</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti>Replacement (or "none")</ti>
<ti>Declares that this eclass should no longer be used</ti>
</tr>
<tr>
<ti><c>@DESCRIPTION:</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti>Multiline freetext</ti>
<ti>Long description for the eclass</ti>
</tr>
<tr>
<ti><c>@EXAMPLE:</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti>Multiline freetext</ti>
<ti>Examples that illustrate various uses of this eclass</ti>
</tr>
@@ -306,13 +306,13 @@ variables are as follows:
<table>
<tr>
<th>tag</th>
- <th>optional?</th>
+ <th>required?</th>
<th>arguments</th>
<th>description</th>
</tr>
<tr>
<ti nowrap="nowrap"><c>@ECLASS-VARIABLE:</c></ti>
- <ti>NO</ti>
+ <ti>Yes</ti>
<ti>Name of the eclass variable to which the documentation applies</ti>
<ti>
This tag applies to eclass specific variables that affect the
@@ -323,7 +323,7 @@ variables are as follows:
</tr>
<tr>
<ti><c>@PRE_INHERIT</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti><d/></ti>
<ti>
This tag describes whether the variable must be defined before
@@ -333,7 +333,7 @@ variables are as follows:
</tr>
<tr>
<ti><c>@USER_VARIABLE</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti><d/></ti>
<ti>
This tag describes whether the variable is unsuitable for use in ebuilds,
@@ -343,7 +343,7 @@ variables are as follows:
</tr>
<tr>
<ti><c>@OUTPUT_VARIABLE</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti><d/></ti>
<ti>
This tag indicates that the variable's value (which will be set by the
@@ -352,7 +352,7 @@ variables are as follows:
</tr>
<tr>
<ti><c>@DEFAULT_UNSET</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti><d/></ti>
<ti>
Indicates that this variable is unset by default if not set by the
@@ -361,7 +361,7 @@ variables are as follows:
</tr>
<tr>
<ti><c>@INCLUDES_EPREFIX</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti><d/></ti>
<ti>
Indicates that the variable is a path which has ${EPREFIX} prepended to it
@@ -369,25 +369,25 @@ variables are as follows:
</tr>
<tr>
<ti><c>@INTERNAL</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti><d/></ti>
<ti>Indicates that the variable is internal to the eclass</ti>
</tr>
<tr>
<ti><c>@REQUIRED</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti><d/></ti>
<ti>Indicates that this variable must be set by the developer</ti>
</tr>
<tr>
<ti><c>@DEPRECATED</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti>Optionally, the name of any replacement variable</ti>
<ti>Declares that this variable should no longer be used in ebuilds</ti>
</tr>
<tr>
<ti><c>@DESCRIPTION:</c></ti>
- <ti>NO</ti>
+ <ti>Yes</ti>
<ti>Multiline freetext</ti>
<ti>Long description for the eclass variable</ti>
</tr>
@@ -414,13 +414,13 @@ documentation are:
<table>
<tr>
<th>tag</th>
- <th>optional?</th>
+ <th>required?</th>
<th>arguments</th>
<th>description</th>
</tr>
<tr>
<ti><c>@FUNCTION:</c></ti>
- <ti>NO</ti>
+ <ti>Yes</ti>
<ti>Name of the function to which the documentation block applies</ti>
<ti>
Documents information about an eclass function such as its calling
@@ -429,7 +429,7 @@ documentation are:
</tr>
<tr>
<ti><c>@USAGE:</c></ti>
- <ti>NO</ti>
+ <ti>Yes</ti>
<ti>List of required and optional arguments to the function</ti>
<ti>
List of arguments that the eclass function accepts, specified in
@@ -443,12 +443,12 @@ documentation are:
<ti>Return value of the function</ti>
<ti>
<p>Description for the value returned by the function.</p>
- <p><b>*</b>: Not optional for functions that return a value.</p>
+ <p><b>*</b>: Required for functions that return a value.</p>
</ti>
</tr>
<tr>
<ti><c>@MAINTAINER:</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti>Multiline freetext</ti>
<ti>
List of contacts for the eclass function. One line per
@@ -457,7 +457,7 @@ documentation are:
</tr>
<tr>
<ti><c>@INCLUDES_EPREFIX</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti><d/></ti>
<ti>
Indicates whether the function returns a path with ${EPREFIX} prepended
@@ -466,7 +466,7 @@ documentation are:
</tr>
<tr>
<ti><c>@INTERNAL</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti><d/></ti>
<ti>
Indicates that the function is internal to the eclass and should
@@ -475,7 +475,7 @@ documentation are:
</tr>
<tr>
<ti><c>@DEPRECATED</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti>Optionally, the name of a replacement function</ti>
<ti>Declares that this function should no longer be used in ebuilds</ti>
</tr>
@@ -485,7 +485,7 @@ documentation are:
<ti>Multiline freetext</ti>
<ti>
<p>Long description for the eclass function.</p>
- <p><b>*:</b> Not optional if <c>RETURN:</c> is absent.</p>
+ <p><b>*:</b> Required if <c>RETURN:</c> is absent.</p>
</ti>
</tr>
</table>
@@ -505,13 +505,13 @@ using the following tags:
<table>
<tr>
<th>tag</th>
- <th>optional?</th>
+ <th>required?</th>
<th>arguments</th>
<th>description</th>
</tr>
<tr>
<ti><c>@VARIABLE:</c></ti>
- <ti>NO</ti>
+ <ti>Yes</ti>
<ti>
Name of the function-specific variable to which the documentation applies
</ti>
@@ -523,7 +523,7 @@ using the following tags:
</tr>
<tr>
<ti><c>@USER_VARIABLE</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti><d/></ti>
<ti>
This tag describes whether the variable is unsuitable for use in ebuilds,
@@ -533,7 +533,7 @@ using the following tags:
</tr>
<tr>
<ti><c>@DEFAULT_UNSET</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti><d/></ti>
<ti>
Indicates that this variable is unset by default if not set by the
@@ -542,31 +542,31 @@ using the following tags:
</tr>
<tr>
<ti><c>@INCLUDES_EPREFIX</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti><d/></ti>
<ti>Indicates that the variable is a path which has ${EPREFIX} prepended</ti>
</tr>
<tr>
<ti><c>@INTERNAL</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti><d/></ti>
<ti>Indicates that the variable is internal to the eclass function</ti>
</tr>
<tr>
<ti><c>@REQUIRED</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti><d/></ti>
<ti>Indicates that this variable must be set by the developer</ti>
</tr>
<tr>
<ti><c>@DEPRECATED</c></ti>
- <ti>YES</ti>
+ <ti>No</ti>
<ti>Optionally, the name of any replacement variable</ti>
<ti>Declares that this variable should no longer be used in ebuilds</ti>
</tr>
<tr>
<ti><c>@DESCRIPTION:</c></ti>
- <ti>NO</ti>
+ <ti>Yes</ti>
<ti>Multiline freetext</ti>
<ti>Long description for the function variable</ti>
</tr>
