Index: openacs-4/packages/acs-templating/tcl/data-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/data-procs.tcl,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-templating/tcl/data-procs.tcl	11 Dec 2003 21:39:57 -0000	1.12
+++ openacs-4/packages/acs-templating/tcl/data-procs.tcl	29 Jul 2006 23:10:33 -0000	1.13
@@ -32,8 +32,19 @@
   return [validate::$type $value_ref $message_ref]
 }
 
-ad_proc -public template::data::validate::integer { value_ref message_ref } {
+ad_proc -public template::data::validate::integer {
+  value_ref
+  message_ref
+} {
+  Validate that a submitted integer contains only an optional sign and
+  the digits 0-9.
 
+  @param value_ref Reference variable to the submitted value
+  @param message_ref Reference variable for returning an error message
+
+  @return True (1) if valid, false (0) if not
+} {
+
   upvar 2 $message_ref message $value_ref value
 
   set result [regexp {^[+-]?\d+$} $value]
@@ -45,11 +56,21 @@
   return $result 
 }
 
-ad_proc -public template::data::validate::naturalnum { value_ref message_ref } {
-  Validates natural numbers data types
-  Will trim leading 0 in order to avoid TCL interpreting it as octal in the future
-  (code borrowed from ad_page_contract_filter_proc_naturalnum)
+ad_proc -public template::data::validate::naturalnum {
+  value_ref
+  message_ref
+} {
+  Validates natural numbers data types.
+
+  Will trim leading 0 in order to avoid TCL interpreting it as octal (code borrowed
+  from ad_page_contract_filter_proc_naturalnum)
+
   @author Rocael Hernandez <roc@viaro.net>
+
+  @param value_ref Reference variable to the submitted value
+  @param message_ref Reference variable for returning an error message
+
+  @return True (1) if valid, false (0) if not
 } {
   upvar 2 $message_ref message $value_ref value
 
@@ -62,8 +83,19 @@
   return $result
 }
 
-ad_proc -public template::data::validate::float { value_ref message_ref } {
+ad_proc -public template::data::validate::float {
+  value_ref
+  message_ref
+} {
+  Validate that a submitted fla contains only an optional sign, and a whole part
+  and fractional part.
 
+  @param value_ref Reference variable to the submitted value
+  @param message_ref Reference variable for returning an error message
+
+  @return True (1) if valid, false (0) if not
+} {
+
   upvar 2 $message_ref message $value_ref value
 
   # Not allowing for scientific notation. Would the databases swallow it?
@@ -76,9 +108,18 @@
   return $result 
 }
 
-ad_proc -public template::data::validate::boolean { value_ref message_ref } {
-  Validates boolean data types
+ad_proc -public template::data::validate::boolean {
+  value_ref
+  message_ref
+} {
+  Validates boolean data types.
+
   @author Roberto Mello <rmello at fslc.usu.edu>
+
+  @param value_ref Reference variable to the submitted value
+  @param message_ref Reference variable for returning an error message
+
+  @return True (1) if valid, false (0) if not
 } {
 
   upvar 2 $message_ref message $value_ref value
@@ -108,20 +149,48 @@
   return $result 
 }
 
-ad_proc -public template::data::validate::text { value_ref message_ref } {
+ad_proc -public template::data::validate::text {
+  value_ref
+  message_ref
+} {
+  Validate that submitted text is valid.  Hmmm ... all submitted text is valid,
+  that's easy!
 
-  # anything is valid for text
+  @param value_ref Reference variable to the submitted value
+  @param message_ref Reference variable for returning an error message
+
+  @return True (1)
+} {
   return 1
 }
 
-ad_proc -public template::data::validate::string { value_ref message_ref } {
+ad_proc -public template::data::validate::string {
+  value_ref
+  message_ref
+} {
+  Validate that a submitted string is valid.  Hmmm ... all submitted strings are valid,
+  that's easy!
 
-  # anything is valid for string
+  @param value_ref Reference variable to the submitted value
+  @param message_ref Reference variable for returning an error message
+
+  @return True (1)
+} {
   return 1
 }
 
-ad_proc -public template::data::validate::keyword { value_ref message_ref } {
+ad_proc -public template::data::validate::keyword {
+  value_ref
+  message_ref
+} {
+  Validate that a submitted keyword consists of alphnumeric or "_" characters.
 
+  @param value_ref Reference variable to the submitted value
+  @param message_ref Reference variable for returning an error message
+
+  @return True (1) if valid, false (0) if not
+} {
+
   upvar 2 $message_ref message $value_ref value
 
   set result [regexp {^[a-zA-Z0-9_]+$} $value]
@@ -133,8 +202,19 @@
   return $result 
 }
 
-ad_proc -public template::data::validate::filename { value_ref message_ref } {
+ad_proc -public template::data::validate::filename {
+  value_ref
+  message_ref
+} {
+  Validate that a submitted filename consists of alphanumeric, "_", or
+  "-" characters.
 
+  @param value_ref Reference variable to the submitted value
+  @param message_ref Reference variable for returning an error message
+
+  @return True (1) if valid, false (0) if not
+} {
+
   upvar 2 $message_ref message $value_ref value
 
   set result [regexp {^[a-zA-Z0-9_-]+$} $value]
@@ -146,8 +226,18 @@
   return $result 
 }
 
-ad_proc -public template::data::validate::email { value_ref message_ref } {
+ad_proc -public template::data::validate::email {
+  value_ref
+  message_ref
+} {
+  Validate that a submitted email address is syntactically correct.
 
+  @param value_ref Reference variable to the submitted value
+  @param message_ref Reference variable for returning an error message
+
+  @return True (1) if valid, false (0) if not
+} {
+
   upvar 2 $message_ref message $value_ref value
 
   set result [util_email_valid_p $value]
@@ -159,8 +249,19 @@
   return $result 
 }
 
-ad_proc -public template::data::validate::url { value_ref message_ref } {
+ad_proc -public template::data::validate::url {
+  value_ref
+  message_ref
+} {
+  Validate that a submitted url is correct.  Accepts an optional http:// or
+  https:// prefix, path, and query string.
 
+  @param value_ref Reference variable to the submitted value
+  @param message_ref Reference variable for returning an error message
+
+  @return True (1) if valid, false (0) if not
+} {
+
   upvar 2 $message_ref message $value_ref value
 
   set expr {^(https?://)?([a-zA-Z0-9_\-\.]+(:[0-9]+)?)?[a-zA-Z0-9_.%/?=&-]+$}
@@ -173,7 +274,10 @@
   return $result 
 }
 
-ad_proc -public template::data::validate::url_element { value_ref message_ref } {
+ad_proc -public template::data::validate::url_element {
+    value_ref
+    message_ref
+} {
 
     Beautiful URL elements that may only contain lower case 
     characters, numbers and hyphens.
@@ -185,6 +289,10 @@
 
     @author Tilmann Singer
 
+    @param value_ref Reference variable to the submitted value
+    @param message_ref Reference variable for returning an error message
+
+    @return True (1) if valid, false (0) if not
 } {
     upvar 2 $message_ref message $value_ref value
 
@@ -198,24 +306,56 @@
     return $result 
 }
 
-ad_proc -public template::data::validate::date { value_ref message_ref } {
+ad_proc -public template::data::validate::date {
+  value_ref
+  message_ref
+} {
+  Validate that a submitted date conforms to the template system's notion
+  of what a date should be.
 
+  @param value_ref Reference variable to the submitted value
+  @param message_ref Reference variable for returning an error message
+
+  @return True (1) if valid, false (0) if not
+} {
+
   upvar 2 $message_ref message $value_ref value
 
   return [template::util::date::validate $value message]
 }
 
-# It was necessary to declare a datatype of "search" in order for the
-# transformation to be applied correctly.  In reality, the transformation
-# should be on the element, not on the datatype.
 
-ad_proc -public template::data::validate::search { value_ref message_ref } {
+ad_proc -public template::data::validate::search {
+  value_ref
+  message_ref
+} {
+  It was necessary to declare a datatype of "search" in order for the
+  transformation to be applied correctly.  In reality, the transformation
+  should be on the element, not on the datatype.
 
+  DRB: in practice a template form datatype is defined by the presence of a
+  validate procdure for that type.
+
+  @param value_ref Reference variable to the submitted value
+  @param message_ref Reference variable for returning an error message
+
+  @return True (1)
+} {
   return 1
 }
 
-ad_proc -public template::data::transform { type value_ref } {
+ad_proc -public template::data::transform {
+  type
+  value_ref
+} {
+  Dispatch procedure for the transform method.  "tranformation" in template
+  systemspeak means to convert the submitted data to the custom datatype structure,
+  usually a list for complex datatypes, just the value for simple datatypes.  The
+  transform method is called after the datatype is validated.
 
+  @param type The data type to be transformed.
+} {
+
   set proc_name [info procs ::template::data::transform::$type]
 
   if { ! [string equal $proc_name {}] } {
Index: openacs-4/packages/acs-templating/tcl/date-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/date-procs.tcl,v
diff -u -r1.36 -r1.37
--- openacs-4/packages/acs-templating/tcl/date-procs.tcl	4 Jun 2006 00:45:48 -0000	1.36
+++ openacs-4/packages/acs-templating/tcl/date-procs.tcl	29 Jul 2006 23:10:33 -0000	1.37
@@ -1176,6 +1176,9 @@
 ad_proc -public template::util::textdate::create {
     {textdate {}}
 } {
+    Build a textdate datatype structure, which is just the string itself for this
+    simple type.
+} {
     return $textdate
 }
 
@@ -1258,8 +1261,18 @@
     }
 }
 
-ad_proc -public template::data::validate::textdate { value_ref message_ref } {
+ad_proc -public template::data::validate::textdate {
+    value_ref
+    message_ref
+} {
+  Validate that a submitted textdate if properly formatted.
 
+  @param value_ref Reference variable to the submitted value.
+  @param message_ref Reference variable for returning an error message.
+
+  @return True (1) if valid, false (0) if not.
+} {
+
     upvar 2 $message_ref message $value_ref textdate
     set error_msg [list]
     if { [exists_and_not_null textdate] } {
Index: openacs-4/packages/acs-templating/tcl/doc-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/doc-procs.tcl,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-templating/tcl/doc-procs.tcl	15 Oct 2003 12:35:51 -0000	1.4
+++ openacs-4/packages/acs-templating/tcl/doc-procs.tcl	29 Jul 2006 23:10:33 -0000	1.5
@@ -21,7 +21,11 @@
 
 namespace eval template {}
 
-ad_proc -public template::parse_directives { code } {
+ad_proc -public template::parse_directives {
+  code
+} {
+  Parse out directives embedded in the code parameter.
+} {
 
   # remove carriage returns if present
   regsub -all {\r|\r\n} $code {\n} code
@@ -160,6 +164,8 @@
 }
 
 ad_proc -public template::verify_datasources {} {
+  @return True (1)
+} {
   return 1
 }
 
Index: openacs-4/packages/acs-templating/tcl/file-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/file-procs.tcl,v
diff -u -r1.8 -r1.9
--- openacs-4/packages/acs-templating/tcl/file-procs.tcl	21 Jun 2005 13:41:46 -0000	1.8
+++ openacs-4/packages/acs-templating/tcl/file-procs.tcl	29 Jul 2006 23:10:33 -0000	1.9
@@ -40,8 +40,18 @@
     return 1
 }
 
-ad_proc -public template::util::file::get_property { what file_list } {
+ad_proc -public template::util::file::get_property {
+    what
+    file_list
+} {
+    Return a property from a file datatype structure.
 
+    @param what Which property to return (filename, etc).
+    @param file_list The file datatype structure.
+
+    @return The requested property from the file datatype structure.
+} {
+
     switch $what {
         filename {
             return [lindex $file_list 0]
Index: openacs-4/packages/acs-templating/tcl/list-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/list-procs.tcl,v
diff -u -r1.35 -r1.36
--- openacs-4/packages/acs-templating/tcl/list-procs.tcl	26 Jul 2006 20:04:32 -0000	1.35
+++ openacs-4/packages/acs-templating/tcl/list-procs.tcl	29 Jul 2006 23:10:33 -0000	1.36
@@ -582,6 +582,8 @@
 ad_proc -public template::list::get_refname {
     {-name:required}
 } {
+    Return a canonical name for the given list template.
+} {
     return "$name:properties"
 }
 
@@ -590,6 +592,17 @@
     {-local_name "list_properties"}
     {-create:boolean}
 } {
+    Bind an upvar reference to a variable at the template parse level to a local
+    variable, optionally giving an error message if it doesn't exist.
+
+    @param name Name of the variable at the template parse level.
+    @param local_name Name of the local variable to bind the reference to, default
+           "list_properties".
+    @param create Boolean which if true suppresses the "not found" error return, for
+           instance when you're building the reference in order to create a new
+           list.
+
+} {
     set refname [get_refname -name $name]
     
     if { !$create_p && ![uplevel \#[template::adp_level] [list info exists $refname]] } {
@@ -604,7 +617,14 @@
     {-override ""}
     {-exclude ""}
 } {
-    @param  and     Set this flag if you want the result to start with an 'and' if the list of where clauses returned is non-empty.
+    Build a URL for the current page with query variables set for the various filters
+    active for the named list.  
+
+    @param name The name of the list
+    @param override Values that export_vars should override
+    @param exclude Values that export_vars should not put in the query string
+
+    @return The current page's URL decorated with the computed query string
 } {
     # Get an upvar'd reference to list_properties
     get_reference -name $name
@@ -940,6 +960,11 @@
 ad_proc -private template::list::prepare_for_rendering {
     {-name:required}
 } {
+    Build all the variable references that are required when rendering a list
+    template.
+
+    @param name The name of the list template we hope to be able to render eventually.
+} {
     set __level [template::adp_level]
 
     # Provide a reference to the list properties for use by the list template
@@ -1088,6 +1113,15 @@
     {-name:required}
     {-style ""}
 } {
+    Simple procedure to render HTML from a list template
+
+    (That's a lame joke, Don)
+
+    @param name The name of the list template.
+    @param style Style template used to render this list template.
+
+    @return HTML suitable for display by your favorite browser.
+} {
     set level [template::adp_level]
     
     # Creates the '_eval' columns and aggregates
@@ -1184,6 +1218,8 @@
 ad_proc -private template::list::render_row {
     {-name:required}
 } {
+    Render one row of a list template.
+} {
     set level [template::adp_level]
 
     # Get an upvar'd reference to list_properties
@@ -1479,6 +1515,12 @@
 ad_proc -public template::list::util_html_to_attributes_string {
     html
 } {
+    Takes a list in array get format and builds HTML attributes from them.
+
+    @param html A misnomer?  The input isn't HTML, the output is HTML.
+
+    @return HTML attributes built from the list in array get format
+} {
     set output {}
     foreach { key value } $html {
         if { ![empty_string_p $value] } {
@@ -1750,6 +1792,8 @@
     {-value:required}
     {-ulevel 1}
 } {
+    Set a property in the named list template.
+} {
     # Get an upvar'd reference to list_properties
     template::list::get_reference -name $list_name
     
@@ -1795,6 +1839,8 @@
     {-spec:required}
     {-ulevel 1}
 } {
+    Set a list of properties in array get format for the given list template.
+} {
     incr ulevel
 
     foreach { property value } $spec {
@@ -2019,6 +2065,13 @@
     {-list_name:required}
     {-filter_name:required}
 } {
+    Build a canonical name from a list and filter name.
+
+    @param list_name List name.
+    @param filter_name Filter name.
+
+    @return Canonical name built from list_name and filter_name.
+} {
     return "$list_name:filter:$filter_name:properties"
 }
 
@@ -2028,6 +2081,8 @@
     {-local_name "filter_properties"}
     {-create:boolean}
 } {
+    Build a reference to the given filter for the given list template.
+} {
     set refname [get_refname -list_name $list_name -filter_name $filter_name]
     
     if { !$create_p && ![uplevel \#[template::adp_level] [list info exists $refname]] } {
@@ -2044,6 +2099,8 @@
     {-value:required}
     {-ulevel 1}
 } {
+    Set a property for the given list and filter.
+} {
     # Get an upvar'd reference to list_properties
     template::list::get_reference -name $list_name
     
@@ -2082,6 +2139,9 @@
     {-spec:required}
     {-ulevel 1}
 } {
+    Set multiple properties for the given list and filter from a list in
+    array get format.
+} {
     incr ulevel
 
     foreach { property value } $spec {
@@ -2100,6 +2160,8 @@
     {-filter_name:required}
     {-property:required}
 } {
+    Return a property from a given list and filter.
+} {
     get_reference \
         -list_name $list_name \
         -filter_name $filter_name
@@ -2111,6 +2173,13 @@
     {-list_name:required}
     {-filter_name:required}
 } {
+    Determine if a given filter exists for a given list template.
+
+    @param list_name The name of the list template.
+    @param filter_name The filter name.
+
+    @return True (1) if the filter exists, false (0) if not.
+} {
     set refname [get_refname -list_name $list_name -filter_name $filter_name]
     
     return [uplevel \#[template::adp_level] [list info exists $refname]]
@@ -2458,6 +2527,8 @@
     {-list_name:required}
     {-orderby_name:required}
 } {
+    Build a canonical name from a list and orderby filter.
+} {
     return "$list_name:orderby:$orderby_name:properties"
 }
 
@@ -2467,6 +2538,8 @@
     {-local_name "orderby_properties"}
     {-create:boolean}
 } {
+    Build a local reference to an orderby filter for a named list template.
+} {
     # Check that the list exists
     template::list::get_reference -name $list_name
 
@@ -2484,6 +2557,8 @@
     {-orderby_name:required}
     {-property:required}
 } {
+    Get a property from an orderby filter for a list template.
+} {
     get_reference \
         -list_name $list_name \
         -orderby_name $orderby_name
@@ -2498,6 +2573,8 @@
     {-value:required}
     {-ulevel 1}
 } {
+    Set a property for an orderby filter in the given list template.
+} {
     # Get an upvar'd reference to list_properties
     template::list::get_reference -name $list_name
     
@@ -2546,6 +2623,9 @@
     {-spec:required}
     {-ulevel 1}
 } {
+    Set multiple properties for the given orderby filter in the given list
+    template from a list in array get format.
+} {
     incr ulevel
 
     foreach { property value } $spec {
Index: openacs-4/packages/acs-templating/tcl/request-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/request-procs.tcl,v
diff -u -r1.5 -r1.6
--- openacs-4/packages/acs-templating/tcl/request-procs.tcl	15 Oct 2003 12:35:51 -0000	1.5
+++ openacs-4/packages/acs-templating/tcl/request-procs.tcl	29 Jul 2006 23:10:33 -0000	1.6
@@ -22,7 +22,12 @@
 namespace eval template {}
 namespace eval template::request {}
 
-ad_proc -public template::request { command args } {
+ad_proc -public template::request {
+  command
+  args
+} {
+  Dispatch procedure for requests.
+} {
   eval request::$command $args
 }
 
Index: openacs-4/packages/acs-templating/tcl/spellcheck-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/spellcheck-procs.tcl,v
diff -u -r1.15 -r1.16
--- openacs-4/packages/acs-templating/tcl/spellcheck-procs.tcl	13 Jan 2005 13:56:01 -0000	1.15
+++ openacs-4/packages/acs-templating/tcl/spellcheck-procs.tcl	29 Jul 2006 23:10:33 -0000	1.16
@@ -49,7 +49,12 @@
     -element_ref:required
     -values:required
 } {
+    Tranform submitted and previously validated input into a spellcheck datastructure.
 
+    @param element_ref Reference variable to the form element.
+    @param values The set of values for that element.
+} {
+
     upvar $element_ref element
 
     # case 1, initial submission of non-checked text: returns {}.
Index: openacs-4/packages/acs-templating/tcl/tab-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/tab-procs.tcl,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-templating/tcl/tab-procs.tcl	15 Oct 2003 12:35:51 -0000	1.3
+++ openacs-4/packages/acs-templating/tcl/tab-procs.tcl	29 Jul 2006 23:10:33 -0000	1.4
@@ -11,8 +11,18 @@
 namespace eval template::widget {}
 namespace eval template::tabstrip {}
 
-ad_proc -public template::widget::tab { element_reference tag_attributes } {
+ad_proc -public template::widget::tab {
+  element_reference
+  tag_attributes
+} {
+  Widget to create one tab in a set of tabs ("tabstrip") in the tabbed UI.
 
+  @param element_reference Reference variable to the form element
+  @param tag_attributes HTML attributes to add to the tag
+
+  @return Form HTML for the widget
+} {
+
   upvar $element_reference element
 
   if { [info exists element(html)] } {
@@ -45,14 +55,24 @@
 namespace eval template::tabstrip {}
 
 # Dispatch proc
-ad_proc -public template::tabstrip { command args } {
+ad_proc -public template::tabstrip {
+  command
+  args
+} {
+  Dispatch procedure for tabstrip.
+} {
   eval template::tabstrip::$command $args
 }
 
 # Create a new tabbed page
 # accepts the -base_url tag
 
-ad_proc -public template::tabstrip::create { dlg_name args } {
+ad_proc -public template::tabstrip::create {
+  dlg_name
+  args
+} {
+  Create a tabstrip, which is a UI tool consisting of a set of clickable tabs.
+} {
 
   template::util::get_opts $args
 
@@ -106,6 +126,8 @@
 ad_proc -public template::tabstrip::add_tab { 
   dlg_name name label template args
 } {
+  Add a tab to the given tabstrip.
+} {
   # Determine the current tab
   set level [template::adp_level]
   upvar #$level $dlg_name:properties properties
@@ -147,7 +169,11 @@
 
 }
 
-ad_proc -public template::tabstrip::set_current_tab { dlg_name tab_name {rel_level 2}} {
+ad_proc -public template::tabstrip::set_current_tab {
+  dlg_name tab_name {rel_level 2}
+} {
+  Set the current tab (to be highlighted as a cue for the user) in the given tabstrip.
+} {
   
   set level [template::adp_level]
   upvar #$level $dlg_name:properties properties 
Index: openacs-4/packages/acs-templating/tcl/util-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/util-procs.tcl,v
diff -u -r1.23 -r1.24
--- openacs-4/packages/acs-templating/tcl/util-procs.tcl	4 Jun 2006 00:45:48 -0000	1.23
+++ openacs-4/packages/acs-templating/tcl/util-procs.tcl	29 Jul 2006 23:10:33 -0000	1.24
@@ -595,7 +595,11 @@
   ns_set put [ns_conn outputheaders] "Set-Cookie" $cookie
 } 
 
-ad_proc -public template::util::quote_html { html } {
+ad_proc -public template::util::quote_html {
+  html
+} {
+  Quote possible HTML tags in the contents of the html parameter.  
+} {
 
   regsub -all \" [ns_quotehtml $html] \\&quot\; html