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

[Michał Górny]

Dnia 30 kwietnia 2017 23:36:46 CEST, kentnl@g.o napisał(a):
>From: Kent Fredric <kentnl@g.o>
>
>@RETURNS is abused presently both as bash exit code values ( that
>is, bash return values ), and capturable STOUT values.
>
>This is problematic, as they're not equivalent: One is passed
>around via $? , and the other requires VAR=$(func) to capture.
>
>Additionally, functions can have both output, and return values,
>and both can be used together.
>
>For example:
>
>  function get_thing_version() {
>    if [[ "${FAIL}" ]]; then
>      echo "libthing not installed"
>      return 1
>    fi
>    echo "1.0"
>    return 0
>  }
>
>  # this line works and MYVAR gets "1.0"
>  # and does not die
>  MYVAR=$(get_thing_version) \
>        || die "Can't get thing version, ${MYVAR}"
>
>  # This dies with the error message communicated from the
>  # function
>  FAIL=1
>  MYVAR=$(get_thing_version) \
>        || die "Can't get thing version, ${MYVAR}"
>
>Hence, a reasonable documentation for a function like this would
>be:
>
>@OUTPUT: version of thing when present, explanation of cause for thing
>missing otherwise
>  @RETURN: 0 on success, non-zero otherwise
>
>Package-Manager: Portage-2.3.4, Repoman-2.3.2
>---
> app-portage/eclass-manpages/files/eclass-to-manpage.awk | 9 +++++++++
> 1 file changed, 9 insertions(+)
>
>diff --git a/app-portage/eclass-manpages/files/eclass-to-manpage.awk
>b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
>index 0b65162c04..0d41f96327 100644
>--- a/app-portage/eclass-manpages/files/eclass-to-manpage.awk
>+++ b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
>@@ -27,6 +27,7 @@
> # The format of functions:
> # @FUNCTION: foo
> # @USAGE: <required arguments to foo> [optional arguments to foo]
>+# @OUTPUT: <values emitted to STDOUT>
> # @RETURN: <whatever foo returns>
> # @MAINTAINER:
> # <optional; list of contacts, one per line>
>@@ -217,6 +218,7 @@ function show_function_header() {
> function handle_function() {
> 	func_name = $3
> 	usage = ""
>+	funcout = ""
> 	funcret = ""
> 	maintainer = ""
> 	internal = 0
>@@ -231,6 +233,8 @@ function handle_function() {
> 	getline
> 	if ($2 == "@USAGE:")
> 		usage = eat_line()
>+	if ($2 == "@OUTPUT:")
>+		funcout = eat_line()
> 	if ($2 == "@RETURN:")
> 		funcret = eat_line()
> 	if ($2 == "@MAINTAINER:")
>@@ -257,6 +261,11 @@ function handle_function() {
> 			print ""
> 		print "Return value: " funcret
> 	}
>+	if (funcout != "") {
>+		if (desc !="")
>+			print ""
>+		print "Outputs: " funcout
>+	}

Move this above return value. Functions usually output before returning.

>
> 	if (blurb == "")
> 		fail(func_name ": no @BLURB found")


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