docs: expand 2 man pages 'Usage' to include VAL macros

Maybe, the biggest obstacle to successfully exploiting
this new library is after those `stacks' are returned.

Unless a user requests all available `items', there is
always a need to translate an actual enumerator into a
relative position within returned stack(s) of results.

So, this patch attempts to bridge that gap by adding a
brief explanation to the existing discussion in Usage.

[ along the way, 'Usage' & 'Caveats' were refactored ]

Signed-off-by: Jim Warner <james.warner@comcast.net>

2 files changed, 54 insertions, 22 deletions

diff --git a/doc/procps.3 b/doc/procps.3
index bd566ec..061e54e 100644
--- a/doc/procps.3
+++ b/doc/procps.3
@@ -86,7 +86,7 @@ with a single function call.
 Thus, a `stack' can be viewed as a variable length record
 whose content and order is determined solely by the user.
 
-As part of each interface there are two unique items.
+As part of each interface there are two unique enumerators.
 The `noop' and `extra' items exist to hold user values.
 They are never set by the library, but the `extra'
 result will be zeroed with each library interaction.
@@ -107,10 +107,26 @@ these interfaces.
 .RB "3. " procps_unref()
 .fi
 
-Optionally, a user may choose to sort results returned from
-a \fBreap\fR function call.
-The \fBsort\fR function parameters \fIstacks\fR and \fInumstacked\fR
-would normally be those returned in the `reaped' structure.
+The \fBget\fR function is used to retrieve a `result' structure for
+a single `item'.
+Alternatively, a \fBGET\fR macro is available when only the return
+value is of interest.
+
+The \fBselect\fR function can retrieve multiple `result' structures
+in a single `stack'.
+
+For unpredictable variable outcomes, the \fBdiskstats\fR, \fBslabinfo\fR
+and \fBstat\fR interfaces export a \fBreap\fR function.
+It is used to retrieve multiple `stacks' each containing multiple
+`result' structures.
+Optionally, a user may choose to \fBsort\fR those results.
+
+To exploit any `stack', and access individual `result' structures,
+a \fIrelative_enum\fR is required as shown in the \fBVAL\fR macro
+defined in the header file.
+Such values could be hard coded as: 0 through numitems-1.
+However, this need is typically satisfied by creating your own
+enumerators corresponding to the order of the `items' array.
 
 .SS Caveats
 The \fBnew\fR, \fBref\fR, \fBunref\fR, \fBget\fR and \fBselect\fR
@@ -125,11 +141,13 @@ In the case of the \fBdiskstats\fR interface, a \fIname\fR parameter
 on the \fBget\fR and \fBselect\fR functions identifies a disk or
 partition name
 
-The \fBdiskstats\fR, \fBslabinfo\fR and \fBstat\fR interfaces support
-unpredictable variable outcomes.
-As such, they export a \fBreap\fR function to retrieve multiple `stacks'
-with a single invocation.
-These same interfaces also provide a \fBsort\fR function.
+For the \fBstat\fR interface, a \fIwhat\fR parameter on the \fBreap\fR
+function identifies whether data for just CPUs or both CPUs and NUMA
+nodes is to be gathered.
+
+When usng the \fBsort\fR function, the parameters \fIstacks\fR and
+\fInumstacked\fR would normally be those returned in the `reaped'
+structure.
 
 .SH RETURN VALUE
 .SS Functions Returning an `int'
diff --git a/doc/procps_pids.3 b/doc/procps_pids.3
index 7fc1880..5ecdff8 100644
--- a/doc/procps_pids.3
+++ b/doc/procps_pids.3
@@ -81,7 +81,7 @@ with a single function call.
 Thus, a `stack' can be viewed as a variable length record
 whose content and order is determined solely by the user.
 
-As part of each interface there are two unique items.
+As part of this interface there are two unique enumerators.
 The `noop' and `extra' items exist to hold user values.
 They are never set by the library, but the `extra'
 result will be zeroed with each library interaction.
@@ -103,10 +103,23 @@ this interface.
 .RB "4. " procps_pids_unref()
 .fi
 
-Optionally, a user may choose to sort results returned from
-a \fBreap\fR or \fBselect\fR function call.
-The \fBsort\fR function parameters \fIstacks\fR and \fInumstacked\fR
-would normally be those returned in the `pids_fetch' structure.
+The \fBget\fR function is an iterator for successive PIDs/TIDs,
+returning those `items' previously identified via \fBnew\fR
+or \fBreset\fR.
+
+Two functions support unpredictable variable outcomes.
+The \fBreap\fR function gathers data for all processes while
+the \fBselect\fR function deals with specific PIDs or UIDs.
+Both can return multiple `stacks' each containing multiple `result'
+structures.
+Optionally, a user may choose to \fBsort\fR such results
+
+To exploit any `stack', and access individual `result' structures,
+a \fIrelative_enum\fR is required as shown in the \fBVAL\fR macro
+defined in the header file.
+Such values could be hard coded as: 0 through numitems-1.
+However, this need is typically satisfied by creating your own
+enumerators corresponding to the order of the `items' array.
 
 .SS Caveats
 The <pids> API differs from others in that those items
@@ -121,16 +134,17 @@ struct pointer must be supplied.
 With \fBnew\fR it must have been initialized to NULL.
 With \fBunref\fR it will be reset to NULL if the reference count reaches zero.
 
-The \fBget\fR function is an iterator, for successive
-PIDs/TIDs, returning those items previously identified
-via \fBnew\fR or \fBreset\fR.
+The \fBget\fR and \fBreap\fR functions use the \fIwhich\fR parameter
+to specify whether just tasks or both tasks and threads are to be fetched.
 
 The \fBselect\fR function requires an array of PIDs or UIDs as
 \fIthese\fR along with \fInumthese\fR to identify which processes
 are to be fetched.
-This function then operates as a subset of \fBreap\fR
-while returning those items previously identified via \fBnew\fR
-or \fBreset\fR.
+This function then operates as a subset of \fBreap\fR.
+
+When usng the \fBsort\fR function, the parameters \fIstacks\fR and
+\fInumstacked\fR would normally be those returned in the `pids_fetch'
+structure.
 
 Lastly, a \fBfatal_proc_unmounted\fR function may be called before
 any other function to ensure that the /proc/ directory is mounted.
@@ -138,7 +152,7 @@ As such, the \fIinfo\fR parameter would be NULL and the
 \fIreturn_self\fR parameter zero.
 If, however, some items are desired for the issuing program (a
 \fIreturn_self\fR other than zero) then the \fBnew\fR call must precede
-it to obtain the required \fIinfo\fR pointer.
+it to identify the \fIitems\fR and obtain the required \fIinfo\fR pointer.
 
 .SH RETURN VALUE
 .SS Functions Returning an `int'