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

[kentnl]

From: Kent Fredric <ken...@gentoo.org>

@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
+       }
 
        if (blurb == "")
                fail(func_name ": no @BLURB found")
-- 
2.12.2