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.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 47F5E15808B for ; Sun, 20 Mar 2022 13:48:18 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 7EEF2E07DF; Sun, 20 Mar 2022 13:48:17 +0000 (UTC) Received: from smtp.gentoo.org (dev.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 5BADDE07DF for ; Sun, 20 Mar 2022 13:48:17 +0000 (UTC) Received: from oystercatcher.gentoo.org (unknown [IPv6:2a01:4f8:202:4333:225:90ff:fed9:fc84]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id 98B9A343162 for ; Sun, 20 Mar 2022 13:48:16 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id 1C6F4D0 for ; Sun, 20 Mar 2022 13:48:15 +0000 (UTC) From: "Ulrich Müller" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Ulrich Müller" Message-ID: <1647784012.3dfa91c478c62400e5849158679bb2e91db7d4da.ulm@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: ulm X-VCS-Committer-Name: Ulrich Müller X-VCS-Revision: 3dfa91c478c62400e5849158679bb2e91db7d4da X-VCS-Branch: master Date: Sun, 20 Mar 2022 13:48:15 +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-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply X-Archives-Salt: d13bea1f-38e4-48f0-bf6b-ddca55013921 X-Archives-Hash: 6b44e2a996256329380953e5ff9668c4 commit: 3dfa91c478c62400e5849158679bb2e91db7d4da Author: Thomas Bracht Laumann Jespersen laumann xyz> AuthorDate: Fri Mar 18 19:54:32 2022 +0000 Commit: Ulrich Müller gentoo 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 laumann.xyz> Signed-off-by: Ulrich Müller 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: - + @ECLASS: - NO + YesName of the eclass being documented Documents various information about the eclass. Must appear as the @@ -212,7 +212,7 @@ summarizes the available documentation tags: @MAINTAINER: - NO + YesOne or more name and email pairs List of maintainers for the eclass to be contacted. One line per @@ -221,7 +221,7 @@ summarizes the available documentation tags: @AUTHOR: - YES + NoOne or more name and email pairs List of authors for the eclass. One line per author. Must start on @@ -230,25 +230,25 @@ summarizes the available documentation tags: @BUGREPORTS: - YES + NoMultiline freetextDescribes how bugs related to this eclass should be reported@VCSURL: - YES + NoA URI stringPoints to the URL of the VCS that contains the eclass source@SUPPORTED_EAPIS: - YES + NoSpace-separated list of EAPIsList of EAPIs supported by this eclass@PROVIDES: - YES + NoSpace-separated list of eclass names List of indirectly inherited eclasses whose functions and variables may be @@ -257,7 +257,7 @@ summarizes the available documentation tags: @BLURB: - NO + YesSingle line freetext Contains a short description for the eclass. Must be on the same @@ -266,19 +266,19 @@ summarizes the available documentation tags: @DEPRECATED: - YES + NoReplacement (or "none")Declares that this eclass should no longer be used@DESCRIPTION: - YES + NoMultiline freetextLong description for the eclass@EXAMPLE: - YES + NoMultiline freetextExamples that illustrate various uses of this eclass @@ -306,13 +306,13 @@ variables are as follows:
tagoptional?required? arguments description
- + @ECLASS-VARIABLE: - NO + YesName of the eclass variable to which the documentation applies This tag applies to eclass specific variables that affect the @@ -323,7 +323,7 @@ variables are as follows: @PRE_INHERIT - YES + No This tag describes whether the variable must be defined before @@ -333,7 +333,7 @@ variables are as follows: @USER_VARIABLE - YES + No This tag describes whether the variable is unsuitable for use in ebuilds, @@ -343,7 +343,7 @@ variables are as follows: @OUTPUT_VARIABLE - YES + No This tag indicates that the variable's value (which will be set by the @@ -352,7 +352,7 @@ variables are as follows: @DEFAULT_UNSET - YES + No Indicates that this variable is unset by default if not set by the @@ -361,7 +361,7 @@ variables are as follows: @INCLUDES_EPREFIX - YES + No Indicates that the variable is a path which has ${EPREFIX} prepended to it @@ -369,25 +369,25 @@ variables are as follows: @INTERNAL - YES + NoIndicates that the variable is internal to the eclass@REQUIRED - YES + NoIndicates that this variable must be set by the developer@DEPRECATED - YES + NoOptionally, the name of any replacement variableDeclares that this variable should no longer be used in ebuilds@DESCRIPTION: - NO + YesMultiline freetextLong description for the eclass variable @@ -414,13 +414,13 @@ documentation are:
tagoptional?required? arguments description
- + @FUNCTION: - NO + YesName of the function to which the documentation block applies Documents information about an eclass function such as its calling @@ -429,7 +429,7 @@ documentation are: @USAGE: - NO + YesList of required and optional arguments to the function List of arguments that the eclass function accepts, specified in @@ -443,12 +443,12 @@ documentation are: Return value of the function

Description for the value returned by the function.

-

*: Not optional for functions that return a value.

+

*: Required for functions that return a value.

 @MAINTAINER: - YES + NoMultiline freetext List of contacts for the eclass function. One line per @@ -457,7 +457,7 @@ documentation are: @INCLUDES_EPREFIX - YES + No Indicates whether the function returns a path with ${EPREFIX} prepended @@ -466,7 +466,7 @@ documentation are: @INTERNAL - YES + No Indicates that the function is internal to the eclass and should @@ -475,7 +475,7 @@ documentation are: @DEPRECATED - YES + NoOptionally, the name of a replacement functionDeclares that this function should no longer be used in ebuilds @@ -485,7 +485,7 @@ documentation are: Multiline freetext

Long description for the eclass function.

-

*: Not optional if RETURN: is absent.

+

*: Required if RETURN: is absent.

tagoptional?required? arguments description
@@ -505,13 +505,13 @@ using the following tags: - + @VARIABLE: - NO + Yes Name of the function-specific variable to which the documentation applies @@ -523,7 +523,7 @@ using the following tags: @USER_VARIABLE - YES + No This tag describes whether the variable is unsuitable for use in ebuilds, @@ -533,7 +533,7 @@ using the following tags: @DEFAULT_UNSET - YES + No Indicates that this variable is unset by default if not set by the @@ -542,31 +542,31 @@ using the following tags: @INCLUDES_EPREFIX - YES + NoIndicates that the variable is a path which has ${EPREFIX} prepended@INTERNAL - YES + NoIndicates that the variable is internal to the eclass function@REQUIRED - YES + NoIndicates that this variable must be set by the developer@DEPRECATED - YES + NoOptionally, the name of any replacement variableDeclares that this variable should no longer be used in ebuilds@DESCRIPTION: - NO + YesMultiline freetextLong description for the function variable
tagoptional?required? arguments description