API-Doc
by Todd Nightingale
This document is designed to explain the ACS API documentation access tools.
Big Picture
The ACS has hundreds of procedures (1478) which define it's internal and external api. Developers need a simple way to access all of the documentation available for the procedures available to them.
The Implementation
The new API-Doc submodule gives users the ability to reach the documentation of any procedure loaded into server memory which has been defined with proc_doc or ad_proc.
- index.tcl allows users to see all the apm packages which have been loaded as well as access to the api-documentation.
- Access to these procedures is through proc-search.tcl. This page takes the following parameters:
- name_weight weighting for a match in parameter name.
- param_weight weighting for a match in a positional or switch.
- doc_weight weighting for a match in main documentation or in @param documentation.
- source_weight weighting for a match in procedure source code.
- query_string string to be searched for.
- search_type "Feeling Lucky" to be punted directly to best hit.
This page either returns the best hits ranked by score, then by name or if the Feeling Lucky option is entered sends the user to the docs for the best hit.
- The documentation for API procedures is available at proc-view.tcl.
Data Model
In order to implicitly synchronize the available procedures and the API documentation, the procedure documentation information is stored in the nsv_array api-doc-procs. Data is inserted into the array by ad_proc when the procedure is loaded into server memory. The api_proc_doc nsv_array contains elements for every defined procedure, so [nsv get api_proc_doc procedure_name] will return the documentation for procedure_name. This information is it self an array with the following fields:
- main A list containing with one element. The documtation taken from the second argument to ad_proc.
- public_p boolean
- private_p boolean
- default_values
- deprecated_p boolean
- switches
- flags
- positionals list of args
- varargs_p boolean
- script file name
- warn_p boolean
- return
These are not all available for all the procedures and procedures can have more defined fields in the array if procs define other @_field_name_ fields in the main documentation
tnight@mit.edu