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.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 649A1139694 for ; Sun, 30 Apr 2017 21:37:05 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 3E33321C073; Sun, 30 Apr 2017 21:36:57 +0000 (UTC) Received: from smtp.gentoo.org (woodpecker.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id DF1F221C012 for ; Sun, 30 Apr 2017 21:36:56 +0000 (UTC) Received: from katipo2.fritz.box (unknown [IPv6:2406:e001:1:d01:de0e:a1ff:fea1:6ec4]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) (Authenticated sender: kentnl) by smtp.gentoo.org (Postfix) with ESMTPSA id CAE2734169C; Sun, 30 Apr 2017 21:36:53 +0000 (UTC) From: kentnl@gentoo.org To: gentoo-dev@lists.gentoo.org Cc: vapier@gentoo.org, tools-portage@gentoo.org, Kent Fredric Subject: [gentoo-dev] [PATCH] app-portage/eclass-manpages: Add support for @OUTPUT Date: Mon, 1 May 2017 09:36:46 +1200 Message-Id: <20170430213646.21683-1-kentnl@gentoo.org> X-Mailer: git-send-email 2.12.2 Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@lists.gentoo.org Reply-to: gentoo-dev@lists.gentoo.org X-Archives-Salt: b6421d31-a464-4853-9abb-9ecfb168fd59 X-Archives-Hash: 5d4ff8d41150ecbd1215bafcabd1b940 From: Kent Fredric @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: [optional arguments to foo] +# @OUTPUT: # @RETURN: # @MAINTAINER: # @@ -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