API Documentation

Jeszra is able to document non-window related source code. This mechanism has been used to generated the Jeszra: API book.

There is no visual interface for API documentation! The Example 9.21, “API Documentation” explains how it´s being used on a Tcl/Tk source-code file. Place your own API documentation scripts in a tcl-source code file and source it from the »Jeszra;« prompt inside the Jeszra shell window.

Example 9.21. API Documentation

# Create a new Tcl/ Template project:
vgmenu::new .gestalt Tcl templates

# The generated project is automatically activated:
[vgmenu::currentInterp] eval {

    # svgdumper.tcl is to be documented:
    set vgfile::var(buffer) \
       [regsub -all ‧ [read2string vg26/library/svgdumper.tcl] {}]


    # The file must be loaded for documentation.
    # Tcl-Introspection is being  used to analyze
    # the source code.
    source vg26/library/svgdumper.tcl

    # Utillity for Documentation:    
    source vg26/library/docbookSVG.tcl
    proc vgfile:::docbookDirectory { } { return Documentation }
    
    # Initiate API-documentation as an addon.
    package require dbkDumper;

    # Make the documentation permanent.
    # Navigate through the specified namespaces
    # and count usage. Safe the file as
    # »svgdumper.xml«.
    vgfile::mkFile Documentation/svgdumper.xml \
       [vgcode::save-docbookAPI dumper {
          vgfile vgcode 
          dumper::docbook
          dumper::resolve
          dumper::transform}]
}

It is also possible to make a pseudo project for generating API-documentation. The Example 9.21, “API Documentation” will have to be transformed into ???.

Example 9.22. Pseudo Project for API-Documentation

# svgdumper.tcl is to be documented:
set vgfile::var(buffer) \
    [regsub -all ‧ [read2string vg26/library/svgdumper.tcl] {}]
source vg26/library/svgdumper.tcl
source vg26/library/docbookSVG.tcl
proc vgfile:::docbookDirectory { } { return Documentation }
    
# Initiate API-documentation as an addon.
package require dbkDumper;

vgfile::mkFile Documentation/svgdumper.xml \
       [vgcode::save-docbookAPI dumper {
          vgfile vgcode 
          dumper::docbook
          dumper::resolve
          dumper::transform}]
    
# API-Documentation done:
exit;