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

[kentnl@gentoo.org]

From: Kent Fredric <kentnl@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