ROBODoc v3.1e Manual

Updated December 1999

ROBODoc, a documentation tool for C, C++, Java, Assembler, Basic, Fortran, LaTeX, Postscript, Tcl/Tk, LISP, Forth, Perl, Shell Scripts, Occam, COBOL, HTML and many other languages. Additional languages can supported by a few modifications to the source code.

Copyright (C) 1994-1999 Frans Slothouber and Jacco van Weert of Maverick Software Development.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

1 Credits

• Original program and idea: Jacco van Weert
• Versions 2.0 and up: Frans Slothouber, Petteri Kettunen, Bernd Koesling, Anthon Pang, Thomas Aglassinger, and Stefan Kost.
• Maintainer: Frans Slothouber (fslothouber@acm.org), The Netherlands.

2 Table of Contents

3 Introduction

ROBODoc is based on the AutoDocs program written some time ago by Commodore. The idea is to include for every function a standard header containing all sorts of information about that procedure/function. An AutoDocs program will extract these headers from the source file and put them in a autodocs-file. This way you can include the program documentation in the source code and is it not necessary to maintain two documents.

ROBODoc is such a program, however ROBODoc has several additions. For one it can generate the documentation in different formats, ASCII, HTML, RTF, LaTeX, and AmigaGuide. Another feature is that it can fully automatically create links within the document, and to other documents. It is also possible to include parts of the source in you document, complete with links. For instance it is possible to include the complete source code of a function, and have the function names in the source point to their documentation. Besides documenting functions, you can also document classes, methods, structures, variables, and constants.

If you never have used AutoDoc or ROBODoc before you might take a look at the example in the Source directory. Run the command:

  make example

This creates the ROBODoc documentation for the ROBODoc program itself and then starts netscape to view the documentation. Also have a look at the source files themselves, they illustrates the use of headers.

ROBODoc can generate the documentation in five different formats:

• HTML format complete with hyperlinks and mark-ups.
• Plain ASCII text-file, this file is very close to what the original AutoDocs program would generate.
• LaTeX
• RTF, Rich Text Format, mostly used on Windows machines before WWW revolution.
• AmigaGuide format, it is the Amiga computer's equivalent HTML. The AmigaGuide program is necessary to view the resulting autodocs-file. (This was the preferred format when the program was written in 1994.)

4 Hardware and software requirements

ROBODoc was developed in 1994 on a standard Amiga 1200, a system with a 20MHz 68020 processor and 2 Mbyte of RAM. It should therefore be no problem to run it on any of the currently available systems :) The complete source code consists of a series of file that can be found in the Source directory. It is written according (hopefully) to the ANSI C standard and uses no special functions, so it should run on every system with an ANSI C-compiler.

5 How to Format Your Code for use with ROBODoc

ROBODoc allows you to mix the program documentation with the source code. It does require though that this documentation has a particular layout so ROBODoc can recognize it. The following header was taken from the original ROBODoc program (many versions back).

           ------------------------------- Header Name
          /                          \
  /****f* financial.library/StealMoney  <---- Begin Marker
  *    ^------- Header Type
  *
  *  <---- Remark Marker
  *  NAME
  *    StealMoney -- Steal money from the Federal Reserve Bank. (V77)
  *  SYNOPSIS  <---- Item Name
  *    error = StealMoney( userName,amount,destAccount,falseTrail )
  *    D0,Z                D0       D1.W    A0         [A1]
  *
  *    BYTE StealMoney
  *         ( STRPTR,UWORD,struct AccountSpec *,struct falseTrail *);
  *  FUNCTION
  *    Transfer money from the Federal Reserve Bank into the
  *    specified interest-earning checking account.  No records of
  *    the transaction will be retained.
  *  INPUTS
  *    userName    - name to make the transaction under.  Popular
  *                  favorites include "Ronald Reagan" and
  *                  "Mohamar Quadaffi".
  *    amount      - Number of dollars to transfer (in thousands).
  *    destAccount - A filled-in AccountSpec structure detailing the
  *                  destination account (see financial/accounts.h).
  *                  If NULL, a second Great Depression will be
  *                  triggered.
  *    falseTrail  - If the DA_FALSETRAIL bit is set in the
  *                  destAccount, a falseTrail structure must be
  *                  provided.
  *  RESULT
  *    error - zero for success, else an error code is returned
  *           (see financial/errors.h).  The Z condition code
  *           is guaranteed.
  *  EXAMPLE
  *    Federal regulations prohibit a demonstration of this function.
  *  NOTES
  *    Do not run on Tuesdays!
  *  BUGS
  *    Before V88, this function would occasionally print the
  *    address and home phone number of the caller on local police
  *    976 terminals.  We are confident that this problem has been
  *    resolved.
  *  SEE ALSO
  *      CreateAccountSpec(),security.device/SCMD_DESTROY_EVIDENCE,
  *      financial/misc.h
  *
  ******  <---- End Marker
  *
  * You can use this space for remarks that should not be included
  * in the documentation.
  *
  */

You would place this headers infront of functions, classes, methods, structure definitions, or any of the major components in your program. The header itself contains a number of items that provide structured information about the component.

There are a number of special markers in a header (indicated in red above). There are two special markers that mark the begin and end of a header. Each line in a header should start with a remark marker. The starts of each item is marked by an Item Name (in all capitals).

5.1 Header Names

ROBODoc makes some assumptions about the structure a project. It a a project consists of a number of modules and that each module consists of a number of components. These components can be anything that you care to document; functions, variables, structures, classes, methods etc.

Projects, modules, and components all have names. The names allow ROBODoc to structure the documentation and create cross-links. Names are defined in the header name. It is either of the form <project name>/<module name> for a module header or of the form <module name>/<component name> for all other headers.

5.2 Header Types

You can provide ROBODoc with some additional information by specifying the header type. The header type tells ROBODoc what kind of component you are documenting. This information allows ROBODoc to create more useful index tables.

The type is identified by a single character, as listed in the following table

Internal headers are special. They can be used to hide certain headers. They are only extracted if specially requested. You could use to document internal functions that you do now want clients to see.

5.3 Begin Marker

The beginning of a header is marked with a special marker. The above header is intended for a program in C. In other programming languages the marker looks slightly different, since each language has its own convention for starting remarks. ROBODoc recognizes the following begin markers:

After these initial four asterisks, there is the character to identify the kind of header, then another asterisks, and then header name. After this you can specify a version number surrounded by "[]". The version number is stored but not used for anything at the moment. All characters after that are ignored.

This might sound terribly complicated, it is not, here are some examples:

A header for a module called analyser in a project called ChessMaster for C, is has version number 1.0

  /****h* ChessMaster/analyser [1.0] *

In Assembler, a function header, for the function init() in the module finance.library:

  ****f* finance.library/init *

In C++, a class header for class Puppet, for the module puppetmaster, version v2.12

  /****c* puppetMaster/Puppet [v2.12] ******

For the same class a method called Puppet::Talk

  /****m* puppetMaster/Puppet::Talk [v2.12] ******

A project header, in Fortran

  C     ****h* ChessMaster/analyser              C

In Basic

  REM ****h* ChessMaster/analyser

5.4 Remark Marker

Each line in the body of a header should start with a remark marker. This marker is stripped from the line and the remaining part is used to generated the documentation. The following markers are recognized by ROBODoc.

5.5 End Marker

A header ends with an end marker. It should contain atleast three asterisks at the start of a line ("***") right after the remark marker. In general ROBODoc will recognize anything that starts with the following as an end marker:

5.6 Header Items

When ROBODoc has found a header it will try to identify the items. It does this by looking for the item name. The following item names are currently supported:

ROBODoc does this so that it can format each item with a different style (colour, font, etc.) if the user want it. These can be specified in the robodoc.defaults file, see the next section more information.

5.7 Source Item

The source item allows you to include part of the source in the documentation as is demonstrated by the following example.

/****f* Robodoc/RB_Panic [2.0d]
 * NAME
 *   RB_Panic -- Shout panic, free resources, and shut down.
 * SYNOPSIS
 *   RB_Panic (cause, add_info)
 *   RB_Panic (char *, char *)
 * FUNCTION
 *   Prints an error message.
 *   Frees all resources used by robodoc.
 *   Terminates program.
 * INPUTS
 *   cause    - pointer to a string which describes the
 *              cause of the error.
 *   add_info - pointer to a string with additional information.
 * SEE ALSO
 *   RB_Close_The_Shop ()
 * SOURCE
 */

  void RB_Panic (char *cause, char *add_info)
  {
    printf ("Robodoc: Error, %s\n",cause) ;
    printf ("         %s\n", add_info) ;
    printf ("Robodoc: Panic Fatal error, closing down...\n") ;
    RB_Close_The_Shop () ; /* Free All Resources */
    exit(100) ;
  }

/*******/

This would create the following documentation

   RB_Panic -- Shout panic, free resources, and shut down.

   RB_Panic (cause, add_info)
   RB_Panic (char *, char *)

   Prints an error message.
   Frees all resources used by robodoc.
   Terminates program.

   cause    - pointer to a string which describes the
              cause of the error.
   add_info - pointer to a string with additional information.

   RB_Close_The_Shop ()

      void RB_Panic (char *cause, char *add_info)
      {
        printf ("Robodoc: Error, %s\n",cause) ;
        printf ("         %s\n", add_info) ;
        printf ("Robodoc: Panic Fatal error, closing down...\n") ;
        RB_Close_The_Shop () ; /* Free All Resources */
        exit(100) ;
      }    

The source item is in an experimental stage at the moment. All lines between the source item and the following item are copied verbatim to the documentation file. It might be possible that certain expressions within the source conflict with the AmigaGuide program or a HTML viewer. If so please report them to me, that is (fslothouber@acm.org), so they can perhaps be solved in a next release a ROBODoc.

6 The ROBODoc Defaults File

The robodoc.default file can be used to change the appearance of the documentation. For each item type you can define how the corresponding text should be rendered. Each line in the default file consists of two parts, the item type and the item attributes. For instance

AUTHOR                    LARGE ITALICS BOLD UNDERLINE

Specifies that the AUTHOR item has the attributes LARGE, ITALICS, BOLD, and UNDERLINE. The effect of each attribute is listed in the following table.

7 Creating Cross Links

Creating hyper links within a document and across documents is the most interesting feature of ROBODoc. A document with such links is much more easier to read. If your source code consists of just one file, creating links is easy. Just tell ROBODoc that you want to have the output in HTML or AmigaGuide format, and it will automatically generate the links. That is, at the beginning of the document it will create a table of contents that consists of links to all your function headers.

ROBODoc will also search the complete text of you documentation for reference to function names, and it will create a link to the documentation of that function.

In most cases, however, your source code does not consists of a single file. It is also possible, however, to create links to other files. This does require the use of some additional files, called xref files. These files can be generated with ROBODoc. These files contain information about in which file and where in the file references can be found.

Lets assume your project is split up in five different source files, and you want to generate links between these five files. What you have to do to accomplish this is to create a xref file for each of those five files.

With the GENXREF option ROBODoc will generate such a xref file from the a source-file. When you use this option, only the xref file is created not the autodocs-file, however you still have to specify the name of the autodocs file because this name is needed for the creation of the xref file.

When all xref files are created you are ready to create the documentation. To do so you use ROBODOC with the XREF option. It needs a parameter which is the name of the file in which the names of all xref files are defined. Notice: this is a file with file names, it has to be created it by hand.

An example will make things more clear. In the ROBODoc archive, under examples/C there are two source files prog1.c and prog2.c. We can create documentation with hyper links from these two files as follows:

First create the xref files:

  robodoc prog1.c prog1.c.html GENXREF prog1.c.xref HTML INTERNAL
  robodoc prog2.c prog2.c.html GENXREF prog2.c.xref HTML INTERNAL

Now there are two xref files: prog1.c.xref and prog2.c.xref. Note that ROBODoc did not create any HTML files, just the xref files. The name prog1.c.html is needed to create the correct xref files. For prog1.c internal headers were also included.

Now create a file with the xref file names. This file will hold only two lines.

You can give it any name, say "xref_files".

  prog1.c.xref
  prog2.c.xref

Now generate the final documentation:

  robodoc prog1.c prog1.c.html XREF xref_files HTML INTERNAL
  robodoc prog2.c prog2.c.html XREF xref_files HTML INTERNAL

Have a look the the documentation generated:

1. prog1.c.html
2. prog2.c.html

7.1 Limitations

ROBODoc knows very little about the grammar of programming languages. Links are created by looking up words in a table. This means that it sometimes creates links where there should be none. For instance if you have a function called usage(). The every time you use the word usage in any of your documentation a link will show up. It also means that sometimes is does not create links where you would like it to create links. Say you include the source code of a method using the source item. Your method uses other methods of the class. You would like to have links pointing to the documentation of these methods each time you use one. They will not appear though. Since to ROBODoc stores the whole name of a method, ie, someClass::MethodName. In the method source you will use just MethodName().

7.2 Automation with make

The whole process of creating documentation with ROBODoc is of course best automated with make. The following is taken from the makefile in the Source directory. It should be easy to addapt this for your project.

#
# First define the names of the documentation files, one for each
# source file.
#
DOCS=analyser.c.html generator.c.html items.c.html util.c.html \
	folds.c.html headers.c.html links.c.html robodoc.c.html \
        analyser.h.html generator.h.html items.h.html util.h.html \
	folds.h.html headers.h.html links.h.html robodoc.h.html \
#
# Generate the corresponding .xref file names.
#
XREF=$(DOCS:.html=.xref)


doc: robodoc.html.xrefs $(DOCS) masterindex.html 

#
# create xrefs file (file with the names of all .xref files).
#
robodoc.html.xrefs: $(XREF)
	/bin/ls *.xref > $@

#
# Rule to create an .xref file.
#
$(XREF): %.xref : %
	robodoc $< $(@:.xref=.html) INTERNAL -g $@ -v

#
# Rule to create an .html file.
#
$(DOCS): %.html : %
	robodoc $< $@ HTML C INTERNAL -v -x robodoc.html.xrefs

#
# Rule to create the master index file.
#
masterindex.html: robodoc.html.xrefs
	robodoc $< $@ INDEX

A simple,

  make doc

is now sufficient to create all documentation.

8 Master Index File

If your project consists of many source files you might want to create a master index file. This file contains links to the documentation generated from each of your source files as well as a list of all "objects" that you documented. All "objects" are listed according to header type, using the following order: Projects, Classes, Methods, Stuctures, Functions, Variables, Constants, Generic, Internal.

This index file is generated based on the information found in your xrefs file. That is the file with the names of all your xref files. So before you can create the master index file you have to create all your xref files.

To generate a master index file use:

   robodoc <xrefs file> <master index file> INDEX  

The master index file can currently only be generated in HTML.

8.1 examples

Here are some examples of master index files

• Master index for a C++ project to be found in Examples/CPP/
• Master index for ROBODoc to be found in Source/.

9 Usage of ROBODoc

When you call ROBODoc you should provide at least two parameters

  robodoc <source file> <documentation file>

Or in case you are creating a master index file

  robodoc <xrefs file> <master index file> INDEX 

Here sourcefile is the file with the program source of which you want to extract the documentation from and documentation file is the file that will contain the extracted documentation. In addition to this you can specify one of the following options:

If you wonder why all the odd ALL CAPS flags are used instead of for instance "-x"; this was how it was done on the Amiga.

The following abbreviations are also allowed:

10 Suggestions and Bugs

If you find any bugs, catch them, put them in a jar, and send them to:

Suggestions are also welcome at this address. Flames can be directed to the sun.