Index: openacs-4/packages/acs-templating/tcl/currency-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/currency-procs.tcl,v
diff -u -r1.10 -r1.11
--- openacs-4/packages/acs-templating/tcl/currency-procs.tcl	27 Feb 2005 22:45:40 -0000	1.10
+++ openacs-4/packages/acs-templating/tcl/currency-procs.tcl	29 Jul 2006 00:35:48 -0000	1.11
@@ -28,24 +28,59 @@
 }
 
 ad_proc -public template::util::currency::create {
-  {leading_symbol {}} {whole_part {}} {separator {}}
-  {fractional_part {}} {trailing_money {}} {format "$ 5 . 2"}
+  {leading_symbol {}}
+  {whole_part {}}
+  {separator {}}
+  {fractional_part {}}
+  {trailing_money {}}
+  {format "$ 5 . 2"}
 } {
+    Create a currency form element.
+
+    @param leading_symbol The leading symbol for the currency format (default: "$")
+    @param whole_part The number of digits in the whole part of the value (default: 5)
+    @param separator The character the separates the whole part from the fractional part
+           (default ".")
+    @param fractional_part The number of digits allowed in the fractional part of the
+           value (default: 2, i.e. US Pennies)
+    @param trailing_money For those currencies that use a trailing rather than leading
+           character in their normal representation
+    @param format The actual format to use in list form
+
+    @return The parameters joined in a six-element list 
+} {
     return [list $leading_symbol $whole_part $separator $fractional_part $trailing_money $format]
 }
 
-ad_proc -public template::util::currency::acquire { type { value "" } } {
+ad_proc -public template::util::currency::acquire {
+    type
+    { value "" }
+} {
     Create a new currency value with some predefined value
     Basically, create and set the currency value
+
+    @param type The set_property type to set (only sql_number supported currently)
+
+    @return The new currency value set to the predefined value
 } {
   set currency_list [template::util::currency::create]
   return [template::util::currency::set_property $type $currency_list $value]
 }
 
-ad_proc -public template::data::validate::currency { value_ref message_ref } {
+ad_proc -public template::data::validate::currency {
+    value_ref
+    message_ref
+} {
     form validation for currency type.
 
-    Should validate according to locale for example, the following forms: "$2.03" "Rs 50.42" "12.52L" "Y5,13c"
+    Should validate according to locale for example, the following forms: "$2.03"
+    "Rs 50.42" "12.52L" "Y5,13c"
+
+    @param value_ref Reference variable to the submitted value
+    @param message_ref Reference variable for returning error messages
+
+    @return true (1) if valid, false (0) if not
+
 } {
     upvar 2 $message_ref message $value_ref value
 
@@ -76,8 +111,15 @@
     }
 }
 
-ad_proc -private template::data::transform::currency { element_ref } {
+ad_proc -private template::data::transform::currency {
+    element_ref
+} {
+    Transform the previously-validated submitted form data into a six-element currency list
 
+    @param element_ref Reference variable to the form element
+
+} {
+
     upvar $element_ref element
     set element_id $element(id)
 
@@ -133,8 +175,25 @@
     }
 }
 
-ad_proc -public template::util::currency::set_property { what currency_list value } {
+ad_proc -public template::util::currency::set_property {
+    what
+    currency_list
+    value
+} {
+    Set a currency value to a set value, with that value being of "what"
+    form.  Currently the only "what" supported is sql_number, it being assumed
+    (somewhat reasonably) that SQL's NUMERIC datatype will be used to store
+    currency data in the database, regardless of locale.
 
+    @param what What kind of value is being passed in (sql_number is the only
+           format supported)
+    @param currency_list A currency data type value
+    @param value The value to set currency_list to
+
+    @return currency_list set to value
+    
+} {
+
     # Erase leading zeroes from the value, but make sure that 00
     # is not completely erased
     set value [template::util::leadingTrim $value]
@@ -164,12 +223,19 @@
     }
 }
 
-ad_proc -public template::util::currency::get_property { what currency_list } {
+ad_proc -public template::util::currency::get_property {
+    what
+    currency_list
+} {
 
     Return a property of a currency list which was created by a 
     currency widget.
 
-    @param what the name of the property (see code for allowed values)
+    The most useful properties that can be returned are sql_number (compatible with
+    SQL's NUMERIC type, historically called NUMBER by Oracle) and display_currency,
+    which takes the value and formats properly.
+
+    @param what The name of the property (see code for allowed values)
     @param currency_list a currency widget list, usually created with ad_form
 
 
@@ -238,8 +304,22 @@
 }
 
 ad_proc -public template::widget::currency {
-    element_reference tag_attributes {mode edit}
+    element_reference
+    tag_attributes
+    {mode edit}
 } {
+    Render a currency widget.
+
+    By default, the currency widget takes the form $ddddd.dd, i.e. US dollars
+    and cents.  You can optionally pass along a format for different currency.
+
+    @param element_reference Reference variable to the form element
+    @param tag_attributes HTML attributes to add to the tag
+    @param mode If edit, the rendered widget allows input, otherwise the values
+           are passed along as hidden input HTML tags
+
+    @return Form HTML for widget
+} {
     upvar $element_reference element
 
     if { [info exists element(html)] } {