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 {}] } {