rtfldoc

Documentation generator that creates webpages from RtflDoc comments in Rtfl source code. Similar to JavaDoc in the Java world.

Usage

rtfldoc <Rtfl file to document>

The generated HTML file will be available in a directory named doc located in the current working directory. The name of the file will be the input Rtfl file's filename with .rtfl replaced with .html.

Building

Before building, clone the repository with the --recursive Git option. This is necessary to pull down the rtfltemp program, which the build process depends on.

Before building, check BUILD_CONFIG and modify it as needed.

Run ./build.sh to build the program. If you just want to run it, use run.sh, which will build and then run with any arguments provided.

To install as an executable called rtfldoc, run install.sh (may need to use sudo).

Documentation Comments

Documentation comments (hereby referred to as "doc comments") start with //@, followed by the attribute name and its value. Singular attributes that apply to the entire module have their first letter capitalized.

Attributes can be applied to the module, global variables (def variables) and functions.

Attributes on global variables and functions must be placed before the declaration of the variable or function.

All text values in doc comments are allowed to contain HTML.

Module Attributes

• //@Name

  The module's formal name.

• //@Desc

  A description of the module.

• //@Version

  The module's version.

• //@Title

  The page title of the generated documentation file.

• //@depends

  Another module that the module depends on. Multiple depends attributes are allowed.

• //@guide

  A line of text or HTML in the module's usage guide. Multiple guide attributes are allowed.

Global Variable Attributes

• //@var

  Describes the global variable.

Function Attributes

• //@desc

  A description of the function.

• //@since

  Specifies the first version of the module in which the function appeared

• //@return

  Describes the return value of the function

• //@param <name>

  Describes the argument with the specified name. Multiple param attributes are allowed.

Example

See the example.rtfl for a demonstration of all doc comment attributes.