doc::parse_file (private)

 doc::parse_file path

Defined in packages/acs-templating/tcl/doc-tcl-procs.tcl

Parse API documentation from a Tcl page API documentation is parsed as follows:

• Document is scanned until a @namespace directive is encountered. The remainder of the file is scanned for @private or @public directives.
• When one of these directives is encountered, the file is scanned up to a proc declaration and the text in between is parsed as documentation for a single procedure.
• The text between the initial @private or @public directive and the next directive is considered a general comment on the procedure

Valid directives in a procedure doc include:

• @author
• @param (for hard parameters)
• @see (should have the form namespace::procedure. A reference to an entire namespace should be namespace::. By convention the API for each namespace should be in a file of the same name, so that a link can be generated automatically).
• @option (for switches such as -foo)
• @return

Reads the text for a file and scans for a namespace directive. When one is encountered, reads until the next namespace or EOF and calls doc::parse_namespace on the accumulated lines to get procedure documentation.

creates a multirow variable in the variable name designated by result_ref with columns namespace_name, proc_name, public_private, author, param, option, see, return and source_text

Note that this format is suitable for passing to array set for creating a lookup on namespace name.

Parameters:

path (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Source code:

    set text [template::util::read_file $path]

    if { [doc::util::text_divider text {\n#\s*@namespace\s+} ] } {

        # the @namespace directive was found, proceed with parsing through comment text
        set result_list [lrange $text 1 end]

        foreach namespace_body $result_list {
            doc::parse_namespace $namespace_body
        }
        return 1
    } else {

        # no @namespace directives found
        return 0
    }

XQL Not present:

Generic, PostgreSQL, Oracle