netmeister.org

Next Previous Table of Contents

3. Usage

The usage of palmdoc is fairly straight-forward. Just type palmdoc -h to see the options it supports. However, we need to mention a few things:
General usage is
palmdoc projectname
where projectname is the name of your project. Say you have a project named "foo":
This means you have a file called "foo.h" and a file "foo.rcp" in the current directory. In foo.h you have specified all globals, enums, structs and functions you are using in this project (no matter how many other files you have). palmdoc now creates a directory foo_doc into which the resulting file is put. If invoked with "palmdoc -d directoryname foo", the output will be placed into the directory "directoryname". palmdoc now starts walking along your files and creates the output.
The file generated is an html-document, named foo_doc.html

Each document consits of: 

    A header:
        [Overview] [Globals] [Enums] [Structs] [Functions] [Forms]

    The body:
        Overview:
            General Description

        Globals:
            List globals
            One line description

        Enums:
            List Enums

        Each Enum:
            Description

        Structs:
            List Structs

        Each Struct:
            Description
            Members

        Functions:
            List Functions

        Each Function:
            Purpose
            Prototype
            Parameters
            Result
            Comment
            See also

        Forms:
            List Forms

On the bottom of each section, and at the bottom of the document, we have a footer:
[Overview] [Globals] [Enums] [Structs] [Functions] [Forms]

In order for palmdoc to function properly (and to make any sense), it is expected that comments are found along the foo.h file:

palmdoc comments are similar to javadoc-comments, with a few modifications: 

/**
  * @description html-text
  * Your description <b>here</b>.
  */

All comments are optional.
The description features complete html-compliance as we parse it as is. This means that you can format the description as you like, with hyperlinks, lists, bold and italics etc.

We expect a general description at the beginning of the in the Header-file: 

/**
  * @general
  * Write a small description of your project.
  *
  */

This is what will show up under "Overview".

**** Important ****
We expect foo.h file to be in the following structure:
If the file is not in this structure, the output might not be correct or pretty. This forces the programmer to keep a clean head(er). We do NOT accept enums or lobals spreaded all over the document. Let's keep things neat.

Once palmdoc is done, you can view the result by opening the file foo_doc/foo_doc.html in a browser.

Next Previous Table of Contents