Index: openacs-4/packages/acs-templating/tcl/widget-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/widget-procs.tcl,v
diff -u -r1.41 -r1.42
--- openacs-4/packages/acs-templating/tcl/widget-procs.tcl	14 Jul 2006 00:25:12 -0000	1.41
+++ openacs-4/packages/acs-templating/tcl/widget-procs.tcl	28 Jul 2006 23:30:09 -0000	1.42
@@ -84,11 +84,32 @@
     return $output
 }
 
-ad_proc -public template::data::validate::party_search { value_ref message_ref } {
+ad_proc -public template::data::validate::party_search { 
+    value_ref
+    message_ref
+} {
+    Validate the party search entry form.
+
+    @param value_ref A reference to the value input by the user.
+    @param message_ref A reference to the form element error field.
+
+    @return true - all input for this datatype is valid.
+} {
     return 1
 }
 
-ad_proc -private template::data::transform::party_search { element_ref } {
+ad_proc -private template::data::transform::party_search {
+    element_ref
+} {
+    Do the actual search of parties using the input value and return a list of lists
+    consisting of (party_name, party_id).
+
+    DRB: The blank string check should actually be in the validate procedure.
+
+    @param element_ref Reference variable to the form element.
+    @return search result or error
+
+} {
     upvar $element_ref element
     set element_id $element(id)
 
@@ -172,7 +193,12 @@
 }
 
 
-ad_proc -public template::widget::search { element_reference tag_attributes } {
+ad_proc -public template::widget::search {
+    element_reference
+    tag_attributes
+} {
+    Return a widget consisting of either a search box or a search pull-down list.
+
     Here is an example of using the search widget with ad_form:
 
 <pre>
@@ -190,6 +216,12 @@
     Can be either a select widget initially if options supplied 
     or a text box which on submit changes to a select widget.
 
+    @param element_reference Reference variable to the form element
+    @param tag_attributes If the "options" attribute is passed in, a select widget
+           is created, otherwise a search text box.
+
+    @return Form HTML for widget
+
 } {
     upvar $element_reference element
 
@@ -214,11 +246,18 @@
 }
 
 ad_proc -public template::widget::textarea {
-    element_reference tag_attributes
+    element_reference
+    tag_attributes
 } {
     A widget for the HTML form input textarea element.  Includes spellchecker.
 
     @see template::util::spellcheck::spellcheck_properties
+
+    @param element_reference Reference to the form element.
+    @param tag_attributes Html attributes to set in the widget.
+
+    @return Form HTML for widget
+
 } {
 
     upvar $element_reference element
@@ -260,6 +299,18 @@
     {value {}}
     {mode edit}
 } {
+    Do the actual construction of a textarea widget, called by various user-callable
+    widgets.
+
+    @param name Name of the widget.
+    @param attribute_reference Reference variable to the tag_attributes passed to the calling
+           widget proc.
+    @param value Optional value
+    @param mode If edit, output the textarea HTML, otherwise pass along the value (if
+           it exists) in a hidden HTML input tag
+
+    @return Form HTML for widget
+} {
     upvar $attribute_reference attributes
 
     if { ![string equal $mode "edit"] } {
@@ -299,8 +350,20 @@
     }
 }
 
-ad_proc -public template::widget::input { type element_reference tag_attributes } {
+ad_proc -public template::widget::input {
+    type
+    element_reference
+    tag_attributes
+} {
+    General proc used by a wide variety of widgets to output input HTML tags.
 
+    @param type The type of widget (checkbox, radio, text etc)
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to hang on the input tag
+
+    @return Form HTML for widget
+} {
+
     upvar $element_reference element
 
     if { [info exists element(html)] } {
@@ -350,8 +413,19 @@
     return $output
 }
 
-ad_proc -public template::widget::text { element_reference tag_attributes } {
+ad_proc -public template::widget::text {
+    element_reference
+    tag_attributes
+} {
 
+    Generate a text widget (not to be confused with textarea)
+
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to add to the tag
+
+    @return Form HTML for widget
+} {
+
     upvar $element_reference element
 
     # Spell-checker
@@ -367,32 +441,72 @@
 
 
 
-ad_proc -public template::widget::file { element_reference tag_attributes } {
+ad_proc -public template::widget::file {
+    element_reference
+    tag_attributes
+} {
+    Generate a file widget.
 
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to add to the tag
+
+    @return Form HTML for widget
+} {
+
     upvar $element_reference element
 
     return [input file element $tag_attributes]
 }
 
 
 
-ad_proc -public template::widget::password { element_reference tag_attributes } {
+ad_proc -public template::widget::password {
+    element_reference
+    tag_attributes
+} {
+    Generate a password input widget.
 
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to add to the tag
+
+    @return Form HTML for widget
+} {
+
     upvar $element_reference element
 
     return [input password element $tag_attributes]
 }
 
 
-ad_proc -public template::widget::hidden { element_reference tag_attributes } {
+ad_proc -public template::widget::hidden {
+    element_reference
+    tag_attributes
+} {
+    Render a hidden input widget.
 
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to add to the tag
+
+    @return Form HTML for widget
+} {
+
     upvar $element_reference element
 
     return [input hidden element $tag_attributes]
 }
 
-ad_proc -public template::widget::submit { element_reference tag_attributes } {
+ad_proc -public template::widget::submit {
+    element_reference
+    tag_attributes
+} {
+    Render a submit input widget.
 
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to add to the tag
+
+    @return Form HTML for widget
+} {
+
     upvar $element_reference element
 
     # always ignore value for submit widget
@@ -401,8 +515,18 @@
     return [input submit element $tag_attributes]
 }
 
-ad_proc -public template::widget::attachment { element_reference tag_attributes } {
+ad_proc -public template::widget::attachment {
+    element_reference
+    tag_attributes
+} {
+    Render an attachment input widget.
 
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to add to the tag
+
+    @return Form HTML for widget
+} {
+
     upvar $element_reference element
 
     set output [input file element $tag_attributes]
@@ -416,22 +540,52 @@
     return $output
 }
 
-ad_proc -public template::widget::checkbox { element_reference tag_attributes } {
+ad_proc -public template::widget::checkbox {
+    element_reference
+    tag_attributes
+} {
+    Render a checkbox input widget.
 
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to add to the tag
+
+    @return Form HTML for widget
+} {
+
     upvar $element_reference element
 
     return [input checkbox element $tag_attributes]
 }
 
-ad_proc -public template::widget::radio { element_reference tag_attributes } {
+ad_proc -public template::widget::radio {
+    element_reference
+    tag_attributes
+} {
+    Render a radio input widget.
 
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to add to the tag
+
+    @return Form HTML for widget
+} {
+
     upvar $element_reference element
 
     return [input radio element $tag_attributes]
 }
 
-ad_proc -public template::widget::button { element_reference tag_attributes } {
+ad_proc -public template::widget::button {
+    element_reference
+    tag_attributes
+} {
+    Render a button input widget.
 
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to add to the tag
+
+    @return Form HTML for widget
+} {
+
     upvar $element_reference element
 
     return [input button element $tag_attributes]
@@ -445,7 +599,20 @@
     {mode edit}
     {widget_type select}
 } {
+    Render a menu widget (a "select" dropdown menu by default).
 
+    @param widget_name Name of the widget
+    @param options_list List of option/value pairs (i.e. dropdown menu items)
+    @param values_list List of values (i.e. the selected default value)
+    @param attribute_reference Reference variable to the caller's tag_attributes param
+    @param mode If "edit" the widget is rendered, otherwise values are passed along
+           using hidden input HTML tags
+    @param widget_type Select, checkbox, etc
+
+    @return Form HTML for widget
+
+} {
+
     upvar $attribute_reference attributes
 
     # Create an array for easier testing of selected values
@@ -519,8 +686,18 @@
     return $output
 }
 
-ad_proc -public template::widget::select { element_reference tag_attributes } {
+ad_proc -public template::widget::select {
+    element_reference
+    tag_attributes
+} {
+    Render a select widget which allows only one value to be selected.
 
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to add to the tag
+
+    @return Form HTML for widget
+} {
+
     upvar $element_reference element
 
     if { [info exists element(html)] } {
@@ -533,8 +710,18 @@
                 $element(name) $element(options) $element(values) attributes $element(mode)]
 }
 
-ad_proc -public template::widget::multiselect { element_reference tag_attributes } {
+ad_proc -public template::widget::multiselect {
+    element_reference
+    tag_attributes
+} {
+    Render a select widget which allows any number of values to be selected.
 
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to add to the tag
+
+    @return Form HTML for widget
+} {
+
     upvar $element_reference element
 
     if { [info exists element(html)] } {
@@ -559,8 +746,16 @@
                 $element(name) $element(options) $element(values) attributes $element(mode)]
 }
 
-ad_proc -public template::data::transform::search { element_ref } {
+ad_proc -public template::data::transform::search {
+    element_ref
+} {
+    Process a submitted search widget's data.
 
+    @param element_ref Reference variable to the form element
+
+    @return Transformed value
+} {
+
     upvar $element_ref element
     set element_id $element(id)
 
@@ -628,8 +823,18 @@
     return [list $value]
 }
 
-ad_proc -public template::widget::comment { element_reference tag_attributes } {
+ad_proc -public template::widget::comment {
+    element_reference
+    tag_attributes
+} {
+    Render a comment widget.
 
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to add to the tag
+
+    @return Form HTML for widget
+} {
+
     upvar $element_reference element
 
     if { [info exists element(html)] } {
@@ -659,9 +864,17 @@
     return $output
 }
 
-ad_proc -public template::widget::block { element_reference tag_attributes } {
-    widget for blocks of radio-buttoned questions
+ad_proc -public template::widget::block {
+    element_reference
+    tag_attributes
 } {
+    Widget for blocks of radio-buttoned questions
+
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to add to the tag
+
+    @return Form HTML for widget
+} {
     upvar $element_reference element
     
     if { [info exists element(html)] } {