+ Declare a procedure with the following enhancements + over regular Tcl "proc": +
+ ++
+ When a parameter is declared as boolean, it creates a variable $param_name_p. + For example: -foo:boolean will create a variable $foo_p. + If the parameter is passed, $foo_p will have value 1. Otherwise, + $foo_p will have value 0. +
++ Boolean named parameters can optionally take a boolean value than can + make your code cleaner. The following example by Michael Cleverly shows why: + If you had a procedure declared as ad_proc foobar {-foo:boolean} { ... }, + it could be invoked as foobar -foo, which could yield some code like + the following in your procedure: +
+
+if {$flush_p} {
+ some_proc -flush $key
+} else {
+ some_proc $key
+}
+
+ + However, you could invoke the procedure as foobar -foo=$some_boolean_value, + which could make your procedure cleaner because you could write instead: + some_proc -flush=$foo_p $key. + +
+ With named parameters, the same rule as the Tcl switch statement apply, + meaning that -- marks the end of the parameters. This is important if + your named parameter contains a value of something starting with a "-". +
+ ++ Here's an example with named parameters, and namespaces (notice the preferred way of + declaring namespaces and namespaced procedures). Ignore the "\" in "\@param", + I had to use it so the api-browser wouldn't think the parameter docs were for ad_proc + itself: +
+ ++
+namespace eval ::foobar {}
+
+ad_proc -public ::foobar::new {
+ {-oacs_user:boolean}
+ {-shazam}
+ {-user_id ""}
+} {
+ The documentation for this procedure should have a brief description of the
+ purpose of the procedure (the WHAT), but most importantly, WHY it does what it
+ does. One can read the code and see what it does (but it's quicker to see a
+ description), but one cannot read the mind of the original programmer to find out
+ what s/he had in mind.
+
+ \@author Roberto Mello
+ \@creation-date 2002-01-21
+
+ \@param oacs_user If this user is already an openacs user. oacs_user_p will be defined.
+ \@param shazam Magical incantation that calls Captain Marvel. Required parameter.
+ \@param user_id The id for the user to process. Optional with default ""
+ (api-browser will show the default automatically)
+} {
+ if { [empty_string_p $user_id] } {
+ # Do something if this is not an empty string
+ }
+
+ if { $oacs_user_p } {
+ # Do something if this is an openacs user
+ }
+}
+
+
+
@param public specifies that the procedure is part of a public API.
@param private specifies that the procedure is package-private.
@param deprecated specifies that the procedure should not be used.
- @param warn specifies that the procedure should generate a warning when invoked (requires that
- -deprecated also be set)
+ @param warn specifies that the procedure should generate a warning
+ when invoked (requires that -deprecated also be set)
@param arg_list the list of switches and positional parameters which can be
provided to the procedure.
@param [doc_string] documentation for the procedure (optional, but greatly desired).