text/html
and text/plain is supported.
- @param script include information about what script this proc lives in?
- @param source include the source code for the script?
- @param proc_name the name of the procedure for which to generate documentation.
- @return the formatted documentation string.
- @error if the procedure is not defined.
+ @param format the type of documentation to generate. Currently, only
+ text/html
and text/plain
are supported.
+ @param script include information about what script this proc lives in?
+ @param source include the source code for the script?
+ @param proc_name the name of the procedure for which to generate documentation.
+ @return the formatted documentation string.
+ @error if the procedure is not defined.
} {
- if { ![string equal $format "text/html"] && \
- ![string equal $format "text/plain"] } {
- return -code error "Only text/html and text/plain documentation are currently supported"
- }
- array set doc_elements [nsv_get api_proc_doc $proc_name]
- array set flags $doc_elements(flags)
- array set default_values $doc_elements(default_values)
-
- if { $script_p } {
- append out "[api_proc_pretty_name $proc_name]
"
- } else {
- append out "[api_proc_pretty_name -link $proc_name]
"
- }
-
- lappend command_line $proc_name
- foreach switch $doc_elements(switches) {
- if { [lsearch $flags($switch) "boolean"] >= 0 } {
- lappend command_line "\[ -$switch \]"
- } elseif { [lsearch $flags($switch) "required"] >= 0 } {
- lappend command_line "-$switch $switch"
- } else {
- lappend command_line "\[ -$switch $switch \]"
+ if { ![string equal $format "text/html"] && \
+ ![string equal $format "text/plain"] } {
+ return -code error "Only text/html and text/plain documentation are currently supported"
}
- }
-
- set counter 0
- foreach positional $doc_elements(positionals) {
- if { [info exists default_values($positional)] } {
- lappend command_line "\[ $positional \]"
+ array set doc_elements [nsv_get api_proc_doc $proc_name]
+ array set flags $doc_elements(flags)
+ array set default_values $doc_elements(default_values)
+
+ if { $script_p } {
+ append out "[api_proc_pretty_name $proc_name]
"
} else {
- lappend command_line "$positional"
+ append out "[api_proc_pretty_name -link $proc_name]
"
}
- }
- if { $doc_elements(varargs_p) } {
- lappend command_line "\[ args... \]"
- }
- append out "[util_wrap_list $command_line]\n\n"
-
- if { $script_p } {
- append out "Defined in $doc_elements(script)"
- }
-
- if { $doc_elements(deprecated_p) } {
- append out "Deprecated."
- if { $doc_elements(warn_p) } {
- append out " Invoking this procedure generates a warning."
- }
- append out "
\n"
- }
-
- append out "[lindex $doc_elements(main) 0]
-
-
-
-"
-
- if { [info exists doc_elements(param)] } {
- foreach param $doc_elements(param) {
- if { [regexp {^([^ \t]+)[ \t](.+)$} $param "" name value] } {
- set params($name) $value
- }
- }
- }
-
- if { [llength $doc_elements(switches)] > 0 } {
- append out "- Switches:
- \n"
+
+ lappend command_line $proc_name
foreach switch $doc_elements(switches) {
- append out "-$switch"
if { [lsearch $flags($switch) "boolean"] >= 0 } {
- append out " (boolean)"
- }
-
- if { [info exists default_values($switch)] && \
- ![empty_string_p $default_values($switch)] } {
- append out " (defaults to
\"$default_values($switch)\"
)"
- }
-
- if { [lsearch $flags($switch) "required"] >= 0 } {
- append out " (required)"
+ lappend command_line "\[ -$switch \]"
+ } elseif { [lsearch $flags($switch) "required"] >= 0 } {
+ lappend command_line "-$switch $switch"
} else {
- append out " (optional)"
+ lappend command_line "\[ -$switch $switch \]"
}
-
- if { [info exists params($switch)] } {
- append out " - $params($switch)"
- }
- append out "
\n"
}
- append out " \n"
- }
-
- if { [llength $doc_elements(positionals)] > 0 } {
- append out "- Parameters:
- \n"
+
+ set counter 0
foreach positional $doc_elements(positionals) {
- append out "$positional"
- if { [info exists default_values($positional)] } {
- if { [empty_string_p $default_values($positional)] } {
- append out " (optional)"
+ if { [info exists default_values($positional)] } {
+ lappend command_line "\[ $positional \]"
} else {
- append out " (defaults to
\"$default_values($positional)\"
)"
+ lappend command_line "$positional"
}
- }
- if { [info exists params($positional)] } {
- append out " - $params($positional)"
- }
- append out "
\n"
}
- append out " \n"
- }
+ if { $doc_elements(varargs_p) } {
+ lappend command_line "\[ args... \]"
+ }
+ append out "[util_wrap_list $command_line]\n\n"
+
+ if { $script_p } {
+ append out "Defined in $doc_elements(script)"
+ }
+
+ if { $doc_elements(deprecated_p) } {
+ append out "Deprecated."
+ if { $doc_elements(warn_p) } {
+ append out " Invoking this procedure generates a warning."
+ }
+ append out "
\n"
+ }
- if { [info exists doc_elements(return)] } {
- append out "
- Returns:
- [join $doc_elements(return) "
"] \n"
- }
+ append out "[lindex $doc_elements(main) 0]
+
+
+
+"
- if { [info exists doc_elements(error)] } {
- append out "- Error:
- [join $doc_elements(error) "
"] \n"
- }
-
- append out [api_format_common_elements doc_elements]
-
- if { $source_p } {
- append out "- Source code:
-
+ if { [info exists doc_elements(param)] } {
+ foreach param $doc_elements(param) {
+ if { [regexp {^([^ \t]+)[ \t](.+)$} $param "" name value] } {
+ set params($name) $value
+ }
+ }
+ }
+
+ if { [llength $doc_elements(switches)] > 0 } {
+ append out "
- Switches:
- \n"
+ foreach switch $doc_elements(switches) {
+ append out "-$switch"
+ if { [lsearch $flags($switch) "boolean"] >= 0 } {
+ append out " (boolean)"
+ }
+
+ if { [info exists default_values($switch)] && \
+ ![empty_string_p $default_values($switch)] } {
+ append out " (defaults to
\"$default_values($switch)\"
)"
+ }
+
+ if { [lsearch $flags($switch) "required"] >= 0 } {
+ append out " (required)"
+ } else {
+ append out " (optional)"
+ }
+
+ if { [info exists params($switch)] } {
+ append out " - $params($switch)"
+ }
+ append out "
\n"
+ }
+ append out " \n"
+ }
+
+ if { [llength $doc_elements(positionals)] > 0 } {
+ append out "- Parameters:
- \n"
+ foreach positional $doc_elements(positionals) {
+ append out "$positional"
+ if { [info exists default_values($positional)] } {
+ if { [empty_string_p $default_values($positional)] } {
+ append out " (optional)"
+ } else {
+ append out " (defaults to
\"$default_values($positional)\"
)"
+ }
+ }
+ if { [info exists params($positional)] } {
+ append out " - $params($positional)"
+ }
+ append out "
\n"
+ }
+ append out " \n"
+ }
+
+ if { [info exists doc_elements(return)] } {
+ append out "- Returns:
- [join $doc_elements(return) "
"] \n"
+ }
+
+ if { [info exists doc_elements(error)] } {
+ append out "- Error:
- [join $doc_elements(error) "
"] \n"
+ }
+
+ append out [api_format_common_elements doc_elements]
+
+ if { $source_p } {
+ append out "- Source code:
-
[ns_quotehtml [info body $proc_name]]
\n"
- }
-
- # No "see also" yet.
-
- append out "
"
-
- return $out
+ }
+
+ # No "see also" yet.
+
+ append out "
"
+
+ return $out
}
ad_proc api_proc_pretty_name {