- Publicity: Public Only All
acs-api-documentation-procs.tcl
Routines for generating API documentation.
- Location:
- packages/acs-api-browser/tcl/acs-api-documentation-procs.tcl
- Created:
- 21 Jun 2000
- Authors:
- Jon Salz <jsalz@mit.edu>
- Lars Pind <lars@arsdigita.com>
- CVS Identification:
$Id: acs-api-documentation-procs.tcl,v 1.72.2.50 2024/07/28 17:00:03 gustafn Exp $
Procedures in this file
- api_add_to_proc_doc (public)
- api_apropos_functions (public)
- api_describe_function (public)
- api_get_body (public)
- api_library_documentation (public)
- api_proc_documentation (public)
- api_proc_link (public)
- api_proc_pretty_name (public)
- api_proc_url (public)
- api_read_script_documentation (public)
- api_script_documentation (public)
- api_type_documentation (public, deprecated)
- apidoc::format_author (public)
- apidoc::format_see (public)
- apidoc::tcl_to_html (public)
- apidoc::tclcode_to_html (public)
Detailed information
api_add_to_proc_doc (public)
api_add_to_proc_doc -proc_name proc_name -property property \ -value value
Add a certain value to a property in the proc doc of the specified proc.
- Switches:
- -proc_name
(required)- name is fully qualified name without leading colons proc procs, XOTcl methods are a triple with the fully qualified class name, then proc|instproc and then the method name.
- -property
(required)- name of property such as "main" "testcase" "calledby" "deprecated_p" "script" "protection"
- -value
(required)- value of the property
- Author:
- Gustaf Neumann
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_api_browser_api_add_to_proc_doc
api_apropos_functions (public)
api_apropos_functions string
- Parameters:
- string
- Returns:
- the functions in the system that contain string in their name and have been defined using ad_proc.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_api_browser_api_apropos_functions
api_describe_function (public)
api_describe_function [ -format format ] proc
Describes the functions in the system that contain string and that have been defined using ad_proc. The description includes the documentation string, if any.
- Switches:
- -format
(defaults to"text/plain"
) (optional)- Parameters:
- proc
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_api_browser_api_describe_function
api_get_body (public)
api_get_body proc_name
This function returns the body of a Tcl proc or an XOTcl method.
- Parameters:
- proc_name - the name spec of the proc
- Returns:
- body of the specified proc
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_api_browser_api_get_body
api_library_documentation (public)
api_library_documentation [ -format format ] path
Generates formatted documentation for a Tcl library file (just the header, describing what the library does).
- Switches:
- -format
(defaults to"text/html"
) (optional)- Parameters:
- path - the path to the file, relative to the OpenACS path root.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_api_browser_trivial_smoke_test
api_proc_documentation (public)
api_proc_documentation [ -format format ] [ -script ] [ -source ] \ [ -xql ] [ -label label ] [ -first_line_tag first_line_tag ] \ [ -proc_type proc_type ] proc_name
Generates formatted documentation for a procedure.
- Switches:
- -format
(optional)- the type of documentation to generate. This parameter is deprecated and has no effect.
- -script
(boolean) (optional)- include information about what script this proc lives in?
- -source
(boolean) (optional)- include the source code for the script?
- -xql
(boolean) (optional)- include the source code for the related xql files?
- -label
(optional)- the label printed for the proc in the header line
- -first_line_tag
(defaults to"<h3>"
) (optional)- tag for the markup of the first line
- -proc_type
(optional)- Parameters:
- proc_name - the name of the procedure for which to generate documentation.
- Returns:
- the formatted documentation string.
- Error:
- if the procedure is not defined.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_api_browser_api_proc_documentation
api_proc_link (public)
api_proc_link [ -source ] proc
- Switches:
- -source
(boolean) (defaults to"1"
) (optional)- Parameters:
- proc
- Returns:
- full HTML link to the documentation for the proc.
- Author:
- Lars Pind <lars@pinds.com>
- Created:
- 14 July 2000
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- documentation__check_deprecated_see
api_proc_pretty_name (public)
api_proc_pretty_name [ -link ] [ -include_debug_controls ] \ [ -hints_only ] [ -proc_type proc_type ] [ -label label ] proc
- Switches:
- -link
(boolean) (optional)- provide a link to the documentation pages
- -include_debug_controls
(boolean) (optional)- -hints_only
(boolean) (optional)- -proc_type
(optional)- -label
(optional)- the label printed for the proc in the header line
- Parameters:
- proc
- Returns:
- a pretty version of a proc name
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_api_browser_api_proc_pretty_name
api_proc_url (public)
api_proc_url [ -source ] proc
- Switches:
- -source
(boolean) (defaults to"1"
) (optional)- Parameters:
- proc
- Returns:
- the URL of the page that documents the given proc.
- Author:
- Lars Pind <lars@pinds.com>
- Created:
- 14 July 2000
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_api_browser_api_proc_pretty_name
api_read_script_documentation (public)
api_read_script_documentation path
Reads the contract from a Tcl content page.
- Parameters:
- path - the path of the Tcl file to examine, relative to the OpenACS root directory.
- Returns:
- a list representation of the documentation element array, or an empty list if the file does not contain a
doc_page_contract
block.- Error:
- if the file does not exist.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_api_browser_api_read_script_documentation
api_script_documentation (public)
api_script_documentation [ -format format ] path
Generates formatted documentation for a content page. Sources the file to obtain the comment or contract at the beginning.
- Switches:
- -format
(defaults to"text/html"
) (optional)- the type of documentation to generate. Currently, only
text/html
is supported.- Parameters:
- path - the path of the Tcl file to examine, relative to the OpenACS root directory.
- Returns:
- the formatted documentation string.
- Error:
- if the file does not exist.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_api_browser_api_script_documentation
api_type_documentation (public, deprecated)
api_type_documentation type
Deprecated. Invoking this procedure generates a warning.
Deprecated: this was part of a feature which used to react to the 'type' property set in ad_page_contract's documentation and generate an extra link in /api-doc/package-view, but currently no upstream script seems to specify this value and no code seems to create necessary 'doc_type_doc' nsv
- Parameters:
- type
- Returns:
- HTML fragment of the API docs.
- See Also:
- /packages/acs-api-browser/www/type-view.tcl
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
apidoc::format_author (public)
apidoc::format_author author_string
Extracts information about the author and formats it into an HTML string.
- Parameters:
- author_string - author information to format. 3 kind of formats are expected: email (a mailto link to the email is generated), whitespace-separated couple "
( )" (a mailto link for email and the name are generated) and free-form (the same input string is returned).
- Returns:
- the formatted result
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_api_browser_apidoc_format_author
apidoc::format_see (public)
apidoc::format_see see
Takes the value in the argument "see" and possibly formats it into a link that will give the user more info about that resource
- Parameters:
- see - a string expected to contain the resource to format
- Returns:
- the html string representing the resource
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_api_browser_apidoc_format_see
apidoc::tcl_to_html (public)
apidoc::tcl_to_html proc_name
Given a proc name, formats it as HTML, including highlighting syntax in various colors and creating hyperlinks to other proc definitions. The inspiration for this proc was the tcl2html script created by Jeff Hobbs.
Known Issues:
- This proc will mistakenly highlight switch strings that look like commands as commands, etc.
- There are many undocumented AOLserver commands including all of the commands added by modules.
- When a proc inside a string has explicitly quoted arguments, they are not formatted.
- regexp and regsub are hard to parse properly. E.g. If we use the start option, and we quote its argument, and we have an ugly regexp, then this code might highlight it incorrectly.
- Parameters:
- proc_name - procedure to format in HTML
- Author:
- Jamie Rasmussen <jrasmuss@mle.ie>
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_api_browser_apidoc_tclcode_to_html
apidoc::tclcode_to_html (public)
apidoc::tclcode_to_html [ -scope scope ] \ [ -proc_namespace proc_namespace ] script
Given a script, this proc formats it as HTML, including highlighting syntax in various colors and creating hyperlinks to other proc definitions. The inspiration for this proc was the tcl2html script created by Jeff Hobbs.
- Switches:
- -scope
(optional)- -proc_namespace
(optional)- Parameters:
- script - script to be formatted in HTML
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_api_browser_apidoc_tclcode_to_html