In his original writeup, espie@ had the terse parenthetical remark

"(yes/no answer instead of full list)" regarding how to use wantarray().
Flesh this out with an example and a bit of explanation to reduce the
risk of misunderstandings and misuse.
Discussed with espie@.

1 files changed, 19 insertions, 2 deletions

diff --git a/usr.sbin/pkg_add/pod/OpenBSD::style.pod b/usr.sbin/pkg_add/pod/OpenBSD::style.pod
index a215a734b85..65943275cdc 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::style.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::style.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::style.pod,v 1.2 2020/01/04 17:13:35 schwarze Exp $
+$OpenBSD: OpenBSD::style.pod,v 1.3 2020/01/05 14:18:40 schwarze Exp $
 
 =head1 NAME
 
@@ -70,9 +70,26 @@ to another function:
 Mark the last expression at the end of a function with an explicit
 B<return> unless the function is is not intended to return anything.
 
-Avoid using the wantarray() function except as an optimzation;
+Avoid using the wantarray() function except as an optimization;
 it should not change the semantics of the subroutine.
+For example, suppose there is a function returning a list,
+and while the question whether the list is empty sometimes
+needs to be asked, the number of elements never matters.
+Such a function can be structured and used as follows:
 
+	sub get_list
+	{
+		if (wantarray) {
+			# build the complete list and return it
+		} else {
+			# only figure out whether the list is empty
+			# and return 0 if it is or 1 otherwise
+		}
+	}
+
+	if (get_list) {
+		# do something that doesn't need the actual elements
+	}
 
 Let methods that tweak an object return the object itself,
 such that methods can be chained: