Multi Language Documentation

Multi Language Documentation
←	Chapter 9. Documentation	→

The wrapper code generation uses »startcommentary«, »startproc« and »endproc« to copy the comment into the generated wrapper code. See Example 9.18, “Lisp Wrapper Commented”.

The default values for the parameters are stated in the generated comment.

Example 9.18. Lisp Wrapper Commented

;; Description : Additional, custom destructor.
;;               Required, in order to remove a
;;               possible local caché.
;; Written     : 07/21/2008, Roger
;;
    (defmethod destroy ((widget-path base)  )
       (format-wish "senddata [~a destroy ]"
       (widget-path base)  )

The generated Python comments support pydoc .

The generated Ruby comments support rdoc, .

Manual Pages for Lisp

Jeszra currently supports Tcl/Tk as the sole project types. Jeszra’s own design is in principal open for other languages and toolkits.

The most important factor for language and toolkit independence is the separation between parser and composer. The same approach applies for the DocBook generation as-well.

As a consequence Jeszra can be tricked into generating documentation for other languages, based on Tcl/Tk projects. These mechanism was employed to generate DocBook refentry documents for the Lisp, Ruby and Python wrapper classes.

# Defines the project type,
# and the programming language
# added to the embedded examples:
proc vgfile::getType {} { return "lisp"}
proc vgfile::docbookLanguage {} {
   return lisp }

# Language specific »signatures« and usage:
proc dumper::docbook::generalForm t
proc dumper::docbook::cgetForm t
proc dumper::docbook::configureForm t
proc dumper::docbook::signatureOf {t c _}
proc dumper::docbook::synopsisOf t

Through getType retrieves the file extension of the project, in the case of Lisp : »lisp« for .lisp.

docbookLanguage is only being used by the DocBook generation. This procedure returns the name of the programming language; which is then used as a language attribute, to select the proper syntax highlighting. An example for Ruby is shown in Example 9.20, “Generated Ruby”

Example 9.19. Customized Lisp Refentry

proc vgfile::getType {} { return "lisp"}
proc vgfile::docbookLanguage {} { return lisp }
proc dumper::docbook::generalForm t {
     return {(<command>option</command>
              <emphasis>object</emphasis>
              ?arg arg ...?)}}
proc dumper::docbook::cgetForm t {
     return {(<command>cget</command>
              <emphasis>object</emphasis> 
              :<emphasis>option</emphasis>)}}
proc dumper::docbook::configureForm t {
     return {(<command>configure</command>
              <emphasis>object</emphasis>
   ?:<emphasis>option</emphasis>?
   ?<emphasis>value option value ...</emphasis>?)}}
proc dumper::docbook::signatureOf {t c _} {
     return [subst {(<command>$c</command>
         <emphasis>object</emphasis> $_)}]}
proc dumper::docbook::synopsisOf t {
     return [subst {<funcsynopsis>
        <funcsynopsisinfo>
          ;; package require $t in Tcl/Tk.
          (with-ltk-$t
             (<command>make-instance</command> '$t
              ?<parameter>options</parameter> ?))
        </funcsynopsisinfo>
      </funcsynopsis>}]}

The code presented inside Example 9.19, “Customized Lisp Refentry” is bundled in a separate package lispDocbook implemented in module lispdocbook.tcl.

All these alterations are to be applied on the project itself –for example inside the shell, on the Local: prompt, to alter the assumed type of a given project. Do not apply these modifications on a modified project, because the modification will be lost.

Jeszra: +-
Local :package require lispDocbook

Manual Pages for Ruby

The mechanism for Ruby wrapper manual pages is identical to Lisp.

The Example 9.20, “Generated Ruby” shows the language attribute for a programlisting, as specified by: vgfile::docbookLanguage.

Example 9.20. Generated Ruby

   <example>
   <title>Using add of goolbar</title>
   <programlisting language="ruby">
require 'tk'
require 'geitems/goolbar'
root = TkRoot.new { title 'Goolbar' }

# Create the toolbar:
toolbar = TkGoolbar.new(root) {
  creator 'frame'
     show 'samson'
     pack { fill x; }
}

# Create a command inside the toolbar:
toolbar.add( 'command', 'samson') {
  label 'Samson'
}

Tk.mainloop
</programlisting>
   </example>

A separate package rubyDocbook performs the customization on a given project.

Manual Pages for Python

The mechanism for Python wrapper manual pages is identical to Lisp.

A separate package pythonDocbook performs the customization on a given project.

←	↖	→
Creating Documents	↑	API Documentation