Next Previous Table of Contents
To show you how palmdoc works, and what a palmdoc-project might look like, let's consider the following "Hello-World" example:
In our directory we have the files "Hello.c", "Hello.h", "HelloRsc.h" and "Hello.rcp".
4.1 Hello.h code
Here's what "Hello.h" looks like:
/**
* @general
* Hello is nothing but a fancly little hello-world program!
* */
#include <Pilot.h>
#include <string.h>
#include "HelloRsc.h"
#ifdef __GNUC__
#include "Callbacks.h"
#endif
#define myAppID 'WRLD'
#define myDBType 'Data'
/**
* We have a comment here that should not show up
*/
int flag = 0; /** used for testing some properties */
Int lform; /** keep track of where user came from */
FieldPtr theField = 0; /** another good reason to make it global here */
VoidHand myRecord; /** point to the record */
UInt index = 0; /** where do we start? */
Ptr RecPointer; /** pointer to record, many functions need this */
char *theRecord; /** the entry into the database */
char nullstring = 0; /** must be global because... */
DmOpenRef myDB; /** reference to teh database, needed for read and write */
char myDBName[] = "HelloWorldDB"; /** name of the database */
/*************************************************
we're done with globals, now the enums
palmdoc should not show this comment
*************************************************/
typedef enum{sessionSym,documentSym,variableSym,
fieldSym,globalSym,localSym} SymbolKind;
typedef enum{intK,charK,boolK} foo;
typedef enum{this, is, a, test} only;
/*************************************************
we're done with enums, now the structs
palmdoc should not show this comment
*************************************************/
typedef struct SYMBOL {
/**
* @description
* a short description of this struct here
* this struct is here only to show how structs are handled
*
**/
char *name;
SymbolKind kind;
union {
struct {int args; struct SymbolTable *dsym;} documentS;
enum{selectF,textF,radioF,resultF} fieldS;
int variableS;
TYPE globalS;
TYPE localS;
} val;
struct SYMBOL *next;
} SYMBOL;
typedef struct GLOBAL {
/**
* @description
* another bogus struct
*
*/
NAME *names;
TYPE type;
struct INIT *init;
struct GLOBAL *next;
} GLOBAL;
typedef struct EXP {
/**
* @description
* a more complicated struct
* to show how nested structs and enums/unions
* would look like
*
*/
int lineno;
TYPE type;
enum{intconstK,trueK,falseK,stringK,identifierK,equalityK,
greaterK,andK,orK,notK,plusK,minusK,timesK,concatK,
divK,modK,rangeK,lengthK,randomK,systemK} kind;
union{
int intconstE;
char *stringE;
struct {char *name; SYMBOL *idsym;} identifierE;
struct {struct EXP *left,*right;} equalityE;
struct {struct EXP *left,*right;} greaterE;
struct {struct EXP *left,*right;} andE;
struct {struct EXP *left,*right;} orE;
struct EXP *notE;
struct {struct EXP *left,*right;} plusE;
struct {struct EXP *left,*right;} minusE;
struct {struct EXP *left,*right;} timesE;
struct {struct EXP *left,*right;} divE;
struct {struct EXP *left,*right;} modE;
struct {struct EXP *left,*right;} concatE;
struct {struct EXP *string,*from,*to;} rangeE;
struct EXP *lengthE;
struct EXP *randomE;
struct EXP *systemE;
} val;
} EXP;
/*************************************************
we're done with structs, now the functions
palmdoc should not show this comment
*************************************************/
static void ReadData(void);
/**
*
* @purpose
* Reads the data from the database
*
* @result
* returns nothing
*
* @comments
* if you want to explain something, do it here
*
* @see
* enter a reference to other documents/functions here
* for example: see <a href="#func2">WriteData</a>
*/
static void WriteData(void);
/**
*
* @purpose
* Writes the data to the database
*
* @result
* returns nothing
*
* @comments
* if you want to explain something, do it here
*
* @see
* enter a reference to other documents/functions here
* for example: see <a href="#func1">ReadData</a>
*/
static Err StartApplication(void);
/**
*
* @purpose
* Initializes everything necessary to start the application
*
* @result
* returns an Err if initialization fails
*
* @comments
* if you want to explain something, do it here
*
* @see
* enter a reference to other documents/functions here
* for example: see <a href="#func4">StopApplication</a>
*/
static Err StopApplication(void);
/**
*
* @purpose
* makes sure everything is fine when we leave the application
*
* @result
* returns an Err if stopping failed
*
* @comments
* if you want to explain something, do it here
*
* @see
* enter a reference to other documents/functions here
* for example: see <a href="#func3">StartApplication</a>
*/
static Boolean TextFormHandleEvent(EventPtr event);
/**
*
* @purpose
* handles all events for the form "TextForm"
*
* @result
* returns true if all's swell, false otherwise
*
* @comments
* if you want to explain something, do it here
*
* @see
* enter a reference to other documents/functions here
*/
static Boolean SelectFormHandleEvent(EventPtr event);
/**
*
* @purpose
* handles all events for the form "Selectform"
*
* @result
* returns true if all's swell, false otherwise
*
* @comments
* if you want to explain something, do it here
*
* @see
* enter a reference to other documents/functions here
*/
static Boolean HelloFormHandleEvent(EventPtr event);
/**
*
* @purpose
* handles all events for the form "Helloform"
*
* @result
* returns nothing
*
* @comments
* if you want to explain something, do it here
*
* @see
* enter a reference to other documents/functions here
*/
static Boolean ApplicationHandleEvent(EventPtr event);
/**
*
* @purpose
* handles ALL events, calls other functions
*
* @result
* returns true if all's swell, false otherwise
*
* @comments
* if you want to explain something, do it here
*
* @see
* enter a reference to other documents/functions here
* for example:
* see<ul><li><a href="#func5">TextFormHandleEvent</a></li>
* <li><a href="#func6">SelectformHandleEvent</a></li>
* <li><a href="#func7">HelloFormHandleEvent</a></li>
* </ul>
*/
static void EventLoop(void);
/**
*
* @purpose
* the loop that handles all events
*
* @result
* returns nothing
*
* @comments
* if you want to explain something, do it here
*
* @see
* enter a reference to other documents/functions here
*/
DWord PilotMain(Word launchCode, Ptr cmdPBP, Word launchFlags);
/**
*
* @purpose
* Main function
*
* @result
* returns nothing
*
* @comments
* if you want to explain something, do it here
*
* @see
* enter a reference to other documents/functions here
*/
Ok, now run:% palmdoc Hello
palmdoc will now create the directory "Hello_doc" and place the output file "Hello_doc.html" in this directory. When you then view the generated file in a browser, the result will look like this.
Next Previous Table of Contents