subr.ex/ex_pkg_{dispatch,exec,restart}.subr: document functions.

3 files changed, 14 insertions, 22 deletions

diff --git a/subr.ex/ex_pkg_dispatch.subr b/subr.ex/ex_pkg_dispatch.subr
index be743593..98852dab 100644
--- a/subr.ex/ex_pkg_dispatch.subr
+++ b/subr.ex/ex_pkg_dispatch.subr
@@ -4,7 +4,7 @@
 #
 
 #
-# exp_pkg_dispatch_complete() - XXX
+# exp_pkg_dispatch_complete() - completes all disabled and finished packages
 # @_dispatch_fn:	top-level dispatch function name
 # @_group_names:	build group name(s)
 # @_pkg_disabled:	list of disabled packages
diff --git a/subr.ex/ex_pkg_exec.subr b/subr.ex/ex_pkg_exec.subr
index 568266e7..08291e45 100644
--- a/subr.ex/ex_pkg_exec.subr
+++ b/subr.ex/ex_pkg_exec.subr
@@ -4,7 +4,7 @@
 #
 
 #
-# exp_pkg_exec_pre() - XXX
+# exp_pkg_exec_pre() - prepare environment for single named package w/ dispatcher
 # @_group_name:		build group name
 # @_pkg_name:		single package name
 # @_restart_at:		optional comma-separated list of build steps at which to rebuild or ALL or LAST
@@ -52,7 +52,7 @@ exp_pkg_exec_pre() {
 };
 
 #
-# exp_pkg_exec_step() - XXX
+# exp_pkg_exec_step() - execute single build steps & update state for single named package w/ dispatcher
 # @_group_name:		build group name
 # @_pkg_name:		single package name
 # @_restart_at:		optional comma-separated list of build steps at which to rebuild or ALL or LAST
@@ -89,7 +89,7 @@ exp_pkg_exec_step() {
 };
 
 #
-# exp_pkg_exec() - XXX
+# exp_pkg_exec() - execute all pertaining build steps & update state for single named package w/ dispatcher
 # @_dispatch_fn:	top-level dispatch function name
 # @_group_name:		build group name
 # @_pkg_name:		single package name
@@ -149,7 +149,7 @@ exp_pkg_exec() {
 };
 
 #
-# ex_pkg_exec() - dispatch single named packages
+# ex_pkg_exec() - prepare environment for, execute all pertaining build steps & update state for single named package w/ dispatcher
 # @_rdispatch_count:		reference to inout variable of dispatcher count
 # @_dispatch_count_cur:		current dispatcher count
 # @_dispatch_count_max:		maximum dispatcher count
diff --git a/subr.ex/ex_pkg_restart.subr b/subr.ex/ex_pkg_restart.subr
index 8624ff39..89f1a461 100644
--- a/subr.ex/ex_pkg_restart.subr
+++ b/subr.ex/ex_pkg_restart.subr
@@ -4,11 +4,10 @@
 #
 
 #
-# exp_pkg_check_restart_at() - XXX
+# exp_pkg_check_restart_at() - check restart (-r) specification for unknown build steps
 # @_rstatus:		out reference to status string
 # @_rspec_at:		in reference to restart build step list
 #
-# Calling convention:	in ref. @_rspec_at
 # Returns:		zero (0) on success, non-zero (>0) on failure
 #
 exp_pkg_check_restart_at() {
@@ -28,12 +27,11 @@ exp_pkg_check_restart_at() {
 };
 
 #
-# exp_pkg_expand_restart_at_spec() - XXX
+# exp_pkg_expand_restart_at_spec() - expand list of virtual build steps and list of build steps into list of build steps w/ operator subspecifications and virtual build steps expanded
 # @_rstatus:		out reference to status string
 # @_rset:		in reference to restart virtual build step set
 # @_rspec_at:		inout reference to restart build step list
 #
-# Calling convention:	in ref. @_rset, inout ref. @_rspec_at
 # Returns:		zero (0) on success, non-zero (>0) on failure
 #
 exp_pkg_expand_restart_at_spec() {
@@ -90,12 +88,11 @@ exp_pkg_expand_restart_at_spec() {
 };
 
 #
-# exp_pkg_expand_restart_at_spec_cmp() - XXX
+# exp_pkg_expand_restart_at_spec_cmp() - expand list of virtual build steps and list of build steps into list of build steps w/ operator subspecifications expanded
 # @_rstatus:		out reference to status string
 # @_rset:		in reference to restart virtual build step set
 # @_rspec_at:		inout reference to restart build step list
 #
-# Calling convention:	in ref. @_rset, inout ref. @_rspec_at
 # Returns:		zero (0) on success, non-zero (>0) on failure
 #
 exp_pkg_expand_restart_at_spec_cmp() {
@@ -147,13 +144,12 @@ exp_pkg_expand_restart_at_spec_cmp() {
 };
 
 #
-# exp_pkg_expand_restart_at_virtual() - XXX
+# exp_pkg_expand_restart_at_virtual() - expand list of build steps into list of build steps w/ expansion of virtual build steps
 # @_rstatus:		out reference to status string
 # @_spec_at:		restart build step list
 # @_rspec_at_new:	out reference to new restart build step list
-# @_rset:		inout reference to restart virtual build step set
+# @_rset:		in reference to restart virtual build step set
 #
-# Calling convention:	inout ref. @_rspec_recursive
 # Returns:		zero (0) on success, non-zero (>0) on failure
 #
 exp_pkg_expand_restart_at_virtual() {
@@ -187,11 +183,10 @@ exp_pkg_expand_restart_at_virtual() {
 };
 
 #
-# exp_pkg_expand_restart_recursive() - XXX
+# exp_pkg_expand_restart_recursive() - expand restart (-r) specification into recursion flag
 # @_rspec:		inout reference to restart {specification,package name list}
 # @_rrecursive:		out reference to recursion flag
 #
-# Calling convention:	inout ref. @_rspec, out ref. @_rrecursive
 # Returns:		zero (0) on success, non-zero (>0) on failure
 #
 exp_pkg_expand_restart_recursive() {
@@ -213,12 +208,11 @@ exp_pkg_expand_restart_recursive() {
 };
 
 #
-# exp_pkg_expand_restart_spec() - XXX
+# exp_pkg_expand_restart_spec() - expand restart (-r) specification into list of build steps
 # @_rstatus:		out reference to status string
 # @_rspec:		inout reference to restart {specification,package name list}
 # @_rspec_at:		out reference to restart build step list
 #
-# Calling convention:	inout ref. @_rspec, out ref. @_rspec_at, out ref. @_rrecursive
 # Returns:		zero (0) on success, non-zero (>0) on failure
 #
 exp_pkg_expand_restart_spec() {
@@ -256,10 +250,9 @@ exp_pkg_expand_restart_spec() {
 };
 
 #
-# exp_pkg_init_restart_at_virtual() - XXX
+# exp_pkg_init_restart_at_virtual() - produce list of virtual build step set in default build steps
 # @_rset:		out reference to restart virtual build step set
 #
-# Calling convention:	out ref. @_rset
 # Returns:		zero (0) on success, non-zero (>0) on failure
 #
 exp_pkg_init_restart_at_virtual() {
@@ -278,13 +271,12 @@ exp_pkg_init_restart_at_virtual() {
 };
 
 #
-# ex_pkg_process_restart_spec() - XXX
+# ex_pkg_process_restart_spec() - process restart (-r) specification into list of build steps and recursion flag
 # @_rstatus:		out reference to status string
 # @_rspec:		inout reference to restart {specification,package name list}
 # @_rspec_at:		out reference to restart build step list
 # @_rrecursive:		out reference to restart recursion flag
 #
-# Calling convention:	inout ref. @_rspec, out ref. @_rspec_at
 # Returns:		zero (0) on success, non-zero (>0) on failure
 #
 ex_pkg_process_restart_spec() {