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):
%3 doc::parse_tcl_library doc::parse_tcl_library (private) doc::parse_file doc::parse_file doc::parse_tcl_library->doc::parse_file doc::parse_namespace doc::parse_namespace (private) doc::parse_file->doc::parse_namespace doc::util::text_divider doc::util::text_divider (private) doc::parse_file->doc::util::text_divider template::util::read_file template::util::read_file (public) doc::parse_file->template::util::read_file

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
[ hide source ] | [ make this the default ]
Show another procedure: