From 2dd1946cfc53392fce7c8c69c3043739e36ac057 Mon Sep 17 00:00:00 2001
From: Michael Pyne <mpyne@kde.org>
Date: Sat, 22 Dec 2012 19:00:00 -0500
Subject: [PATCH] api: Document process_arguments.

---
 kdesrc-build                | 39 +++++++++++++++++++++++++------------
 modules/ksb/BuildContext.pm |  2 ++
 2 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/kdesrc-build b/kdesrc-build
index 04c90ea..ea3e9f6 100755
--- a/kdesrc-build
+++ b/kdesrc-build
@@ -1194,15 +1194,27 @@ sub handle_set_env
     return 1;
 }
 
-# Subroutine to process the command line arguments, which should be passed as
-# a list. The list of module names passed on the command line will be returned,
-# In addition, a second parameter should be passed, a reference to a hash that
-# will hold options that cannot be set until the rc-file is read.
-#
-# NOTE: One exception to the return value is that if --run is passed, the list
-# of options to pass to the new program is returned instead (you can tell by
-# evaluating the '#start-program' option.
-# NOTE: Don't call finish() from this routine, the lock hasn't been obtained.
+# Function: process_arguments
+#
+# Processes the command line arguments, which are used to modify the given
+# <BuildContext> and possibly return a list of <Modules>.
+#
+# Phase:
+#  initialization - Do not call <finish> from this function.
+#
+# Parameters:
+#  ctx - BuildContext in use.
+#  pendingOptions - hashref to hold parsed modules options to be applied later.
+#    *Note* this must be done separately, it is not handled by this subroutine.
+#  @options - The remainder of the arguments are treated as command line
+#    arguments to process.
+#
+# Returns:
+#  - List of <ksb::Modules> that represent modules specifically entered on the
+#    command-line, _or_
+#  - List of options to pass to a command named by the --run command line
+#    option. (This is true if and only if the _ctx_ ends up with the
+#    _#start-program_ option set).
 sub process_arguments
 {
     my $ctx = assert_isa(shift, 'ksb::BuildContext');
@@ -2291,9 +2303,12 @@ EOF
     return $result;
 }
 
-# Subroutine to exit the script cleanly, including removing any
-# lock files created.  If a parameter is passed, it is interpreted
-# as an exit code to use
+# Function: finish
+#
+# Exits the script cleanly, including removing any lock files created.
+#
+# Parameters:
+#  [exit] - Optional; if passed, is used as the exit code, otherwise 0 is used.
 sub finish
 {
     my $ctx = assert_isa(shift, 'ksb::BuildContext');
diff --git a/modules/ksb/BuildContext.pm b/modules/ksb/BuildContext.pm
index 9a428a6..e08e6ef 100644
--- a/modules/ksb/BuildContext.pm
+++ b/modules/ksb/BuildContext.pm
@@ -1,5 +1,7 @@
 package ksb::BuildContext;
 
+# Class: BuildContext
+#
 # This contains the information needed about the build context, e.g.  list of
 # modules, what phases each module is in, the various options, etc.