Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: Add support for @DEFAULT-VALUE

[Michał Górny]

Dnia 30 kwietnia 2017 23:37:41 CEST, kentnl@g.o napisał(a):
>From: Kent Fredric <kentnl@g.o>
>
>@DEFAULT-VALUE allows eclasses to document the default values they
>will inject when eclass-to-manpage can't extract it.
>
>When eclass-to-manpage *can* extract it, it adds a warning when
>the extracted value is different from that declared, (but the
>declared value still takes precedence)
>
>Note: there is a pre-exisitng poorly documented hack where
>
>  # FOO=VALUE
>
>In a comment serves as a fallback for literal value parsing, which
>can supplement DEFAULT-VALUE in a less clear way.
>
>But due to the nature of this syntax, its not trivial to identify
>which eclasses are, and aren't using it as variables are routinely
>commented without intending them to be used as documentation.
>
>Some such commented assignments lurk in @CODE examples, which are
>surely not intended to be extracted as their values
>
>Subsequently, if present, @DEFAULT-VALUE will also trump any such
>commented assignments
>---
>.../eclass-manpages/files/eclass-to-manpage.awk     | 21
>+++++++++++++++++----
> 1 file changed, 17 insertions(+), 4 deletions(-)
>
>diff --git a/app-portage/eclass-manpages/files/eclass-to-manpage.awk
>b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
>index 0d41f96327..d6ed59efd9 100644
>--- a/app-portage/eclass-manpages/files/eclass-to-manpage.awk
>+++ b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
>@@ -40,6 +40,7 @@
> # [@DEFAULT_UNSET]
> # [@INTERNAL]
> # [@REQUIRED]
>+# @DEFAULT-VALUE: <initial value>

I think you meant to make it [optional].

> # @DESCRIPTION:
> # <required; blurb about this variable>
> # foo="<default value>"
>@@ -49,6 +50,7 @@
> # [@DEFAULT_UNSET]
> # [@INTERNAL]
> # [@REQUIRED]
>+# @DEFAULT-VALUE: <initial value>
> # @DESCRIPTION:
> # <required; blurb about this variable>
> # foo="<default value>"
>@@ -283,6 +285,7 @@ function _handle_variable() {
> 	default_unset = 0
> 	internal = 0
> 	required = 0
>+	default_value = ""
>
> 	# make sure people haven't specified this before (copy & paste error)
> 	if (all_vars[var_name])
>@@ -299,6 +302,10 @@ function _handle_variable() {
> 			internal = 1
> 		else if ($2 == "@REQUIRED")
> 			required = 1
>+		else if ($2 == "@DEFAULT-VALUE:") {
>+			sub(/^# @[A-Z_]*:[[:space:]]*/,"")

Any reason you can't just eat_line?

>+			default_value = $0
>+		}
> 		else
> 			opts = 0
> 	}
>@@ -315,15 +322,21 @@ function _handle_variable() {
> 		op = "?="
> 		regex = "^[[:space:]]*:[[:space:]]*[$]{" var_name ":?=(.*)}"
> 		val = gensub(regex, "\\1", 1, $0)
>-		if (val == $0) {
>-			if (default_unset + required + internal == 0)
>+	}
>+	if (default_value != "") {
>+		if ( val != $0 && default_value != val )
>+			warn( var_name ": extracted different from DEFAULT-VALUE: "
>default_value " <=> " val )
>+		op  = "="
>+		val = default_value
>+	}
>+	if ( val == $0 ) {
>+		if (default_unset + required + internal == 0)
> 				warn(var_name ": unable to extract default variable content: " $0)
> 			val = ""
>-		} else if (val !~ /^["']/ && val ~ / /) {
>+	} else if (val !~ /^["']/ && val ~ / /) {
> 			if (default_unset == 1)
> 				warn(var_name ": marked as unset, but has value: " val)
> 			val = "\"" val "\""
>-		}
> 	}
> 	if (length(val))
> 		val = " " op " \\fI" val "\\fR"


-- 
Best regards,
Michał Górny (by phone)