1 |
From: Kent Fredric <kentnl@g.o> |
2 |
|
3 |
@RETURNS is abused presently both as bash exit code values ( that |
4 |
is, bash return values ), and capturable STOUT values. |
5 |
|
6 |
This is problematic, as they're not equivalent: One is passed |
7 |
around via $? , and the other requires VAR=$(func) to capture. |
8 |
|
9 |
Additionally, functions can have both output, and return values, |
10 |
and both can be used together. |
11 |
|
12 |
For example: |
13 |
|
14 |
function get_thing_version() { |
15 |
if [[ "${FAIL}" ]]; then |
16 |
echo "libthing not installed" |
17 |
return 1 |
18 |
fi |
19 |
echo "1.0" |
20 |
return 0 |
21 |
} |
22 |
|
23 |
# this line works and MYVAR gets "1.0" |
24 |
# and does not die |
25 |
MYVAR=$(get_thing_version) \ |
26 |
|| die "Can't get thing version, ${MYVAR}" |
27 |
|
28 |
# This dies with the error message communicated from the |
29 |
# function |
30 |
FAIL=1 |
31 |
MYVAR=$(get_thing_version) \ |
32 |
|| die "Can't get thing version, ${MYVAR}" |
33 |
|
34 |
Hence, a reasonable documentation for a function like this would |
35 |
be: |
36 |
|
37 |
@OUTPUT: version of thing when present, explanation of cause for thing missing otherwise |
38 |
@RETURN: 0 on success, non-zero otherwise |
39 |
|
40 |
Package-Manager: Portage-2.3.4, Repoman-2.3.2 |
41 |
--- |
42 |
app-portage/eclass-manpages/files/eclass-to-manpage.awk | 9 +++++++++ |
43 |
1 file changed, 9 insertions(+) |
44 |
|
45 |
diff --git a/app-portage/eclass-manpages/files/eclass-to-manpage.awk b/app-portage/eclass-manpages/files/eclass-to-manpage.awk |
46 |
index 0b65162c04..0d41f96327 100644 |
47 |
--- a/app-portage/eclass-manpages/files/eclass-to-manpage.awk |
48 |
+++ b/app-portage/eclass-manpages/files/eclass-to-manpage.awk |
49 |
@@ -27,6 +27,7 @@ |
50 |
# The format of functions: |
51 |
# @FUNCTION: foo |
52 |
# @USAGE: <required arguments to foo> [optional arguments to foo] |
53 |
+# @OUTPUT: <values emitted to STDOUT> |
54 |
# @RETURN: <whatever foo returns> |
55 |
# @MAINTAINER: |
56 |
# <optional; list of contacts, one per line> |
57 |
@@ -217,6 +218,7 @@ function show_function_header() { |
58 |
function handle_function() { |
59 |
func_name = $3 |
60 |
usage = "" |
61 |
+ funcout = "" |
62 |
funcret = "" |
63 |
maintainer = "" |
64 |
internal = 0 |
65 |
@@ -231,6 +233,8 @@ function handle_function() { |
66 |
getline |
67 |
if ($2 == "@USAGE:") |
68 |
usage = eat_line() |
69 |
+ if ($2 == "@OUTPUT:") |
70 |
+ funcout = eat_line() |
71 |
if ($2 == "@RETURN:") |
72 |
funcret = eat_line() |
73 |
if ($2 == "@MAINTAINER:") |
74 |
@@ -257,6 +261,11 @@ function handle_function() { |
75 |
print "" |
76 |
print "Return value: " funcret |
77 |
} |
78 |
+ if (funcout != "") { |
79 |
+ if (desc !="") |
80 |
+ print "" |
81 |
+ print "Outputs: " funcout |
82 |
+ } |
83 |
|
84 |
if (blurb == "") |
85 |
fail(func_name ": no @BLURB found") |
86 |
-- |
87 |
2.12.2 |