Documentation‎ > ‎

Using zudocu

It is often useful to write brief documentation right in the source code.
The tool "zudocu" extracts this and produces HTML.

Example

       #= The Label class is used for simple text widgets.
       #  this line doesn't show up.
       #: example
       #%   ZWT.Button hello = NEW("hello!")
       #%   hello.setStyle(NEW().setColor(NEW("red"))
       CLASS Label EXTENDS Widget
         #= Create a new Label with the text |text|.
         #> text: Any valid string.  NIL is equal to an empty string.
         PROC NEW(string text)
         ...
         #= Set the text in the Label to |text|.
         #- If the Label is visible it is updated immediately.
         #> text: Any valid string.  NIL is equal to an empty string.
         #> Returns THIS for chaining.
         FUNC setText(string text) Label
         ...
         #= Set the main style to |style|.
         #- Any previous style is dropped.
         #> style: When NIL the style is cleared.
         #> Returns THIS for chaining.
         FUNC setStyle(Style style) Label
         ...

Produces an HTML page like this:

CLASS Label @directory

summary

     

The Label class is used for simple text widgets.

   ZWT.Button hello = NEW("hello!")
   hello.setStyle(NEW().setColor(NEW("red"))
NEW(text) @file Create a new Label with the text |text|.
$setText(text) Label @file Set the text in the Label to |text|.
$setStyle(style) Label @file Set the main style to |style|.
 

members (alphabetically)

     

PROC NEW(string text) @file

     

Create a new Label with the text |text|.

FUNC $setStyle(Style style) Label @file

     

Set the main style to |style|.

Any previous style is dropped.

FUNC $setText(string text) Label @file

     

Set the text in the Label to |text|.

If the Label is visible it is updated immediately.


Special Comments

 #= text
 Summary, should be one or two lines.  Tells what the method is for.
 #- text
 Additional information, explains what the method does exactly.
 #% text
 An example, uses different background and mono spaced font
 #: name
 Start a new section with header "name"
 #+ name
 Additional information for argument "name"
 #+ returns
 Additional information for the return value
 #+ throws   
 Additional information about exceptions
 #*name Start a new footer section "name", positioned below the other information
 #* text
 Continue the footer section
 #x? text
 (where x is one of =, -, : + or *) don't mention this item in the table of contents.
 #x> text
 (where x is one of =, -, :, + or *) don't escape HTML, use text literally

 

Formatting

A wiki-like syntax is used for formatting.

simple list:

          # - list item one
          #      continued
          # - list item two
          # below the list

     shows up as:
  • list item one continued
  • list item two
below the list

Marking argument names and links to other classes and methods:

           #  argument |text| is used just like in @Widget.

An URL can be entered in between three @:

           #  See @http://www.zimbu.org/documentation@this page@ for more information.

To be continued....

Comments