oxdoc user's manual

Table of contents

set oxdoc=c:/program files/oxdoc

Finally, you may want to edit oxdoc.xml in the bin directory. This file contains general settings for oxdoc. See the Configuration section for more information.

3. Using oxdoc

oxdoc *.ox

/** This file provides the class `Lumberjack`, an abstract representation
of a lumber jack **/

/** The Lumberjack class represents a lumber jack.  A lumber jack can sleep
by using the `Lumberjack::sleep` method.

@example <pre>
decl L = new Lumberjack();
L.sleep(5);
</pre>

@author Y. Zwols **/
class Lumberjack {
   decl wearsWomensClothes;
   isOk();
   sleep(const hours);
};

/** Checks whether this lumber jack is okay
   @returns TRUE if this lumber jack is okay, FALSE if not.
   @comments In the current implementation, lumber jacks are okay if and only
   if they wear women's clothing.
   @see Lumberjack **/
Lumberjack::isOk() {
   if (this.wearsWomensClothes) 
      return TRUE;
   else
      return FALSE;
}

/** Make the lumber jack sleep for a specified number of hours. A message
is printed to show that he has slept.
   @param hours Number of hours to sleep. Has to be integer.
   @comments The lumber jack cannot sleep more than 24 hours a day. **/
Lumberjack::sleep(const hours) {
   println("The lumber jack is asleep");
   println("(", hours, " hours later...)");
   println("The lumber jack wakes up");
}

Also, the first sentence of the comment block is taken as a summary of the documentation block. This first sentence appears in e.g. the project home page and the methods table. oxdoc recognizes the first sentence by scanning for a period followed by a white space. This may have some undesired effects when a period in the first sentence doesn't indicate the end of a sentence, e.g. in the sentence This class implements Prof. John's algorithm, where the part This class implements Prof. will be taken as a summary. This can be avoided by placing   (a non-breaking space) just after Prof. Moreover, it is possible to include any HTML tag. This may be useful for inclusing of images, or adding more intricate mark up.

3.3. Types of documentation blocks

• File documentation. The comment block starting at the first line of a file is reserved as documentation corresponding to the file.
  Allowed sections: @see, @example, @comments, @author, @version.

• Class documentation. The comment block right before a class definition is treated as class documentation.
  Allowed sections: @see, @example, @comments, @author, @version.

• Method/function documentation. The comment block right before the body of a function or class method is treated as documentation for that function or method.
  Allowed sections: @see, @example, @comments, @param, @returns.

• @param describes a parameter or argument of a function. The first word after the @param keyword is treated as the name of the parameter. More than one parameter can be described by adding more @param sections.
• @see gives a cross reference. References have to match the exact name of other entities. Also, references have to be separated by commas.

Be sure to read the configuration chapter to set up oxdoc so it can find the programs required for this (latex and dvipng).

Once you've set up the connection with LaTeX, adding formules is done by putting them between single or double dollar ($) signs. For example:

/** Calculate the OLS estimates for the model $y = X\beta$.
 @returns The OLS estimate $\hat\beta = (X'X)^{-1}X'y$.
 **/
regression(X, y) {
   return invert(X'X)*X'y;
}

Note: dvipng generates partially transparent graphics files. These files are currently not supported by Internet Explorer 6.0. Supposedly, this will be fixed in version 7.0. For the time being, I recommended using Mozilla Firefox to view documentation files that include formulae at this point. At some later point, I will add a switch to turn of transparent PNG files.

3.5. Cross-referencing

1. the directory in which oxdoc.jar is located (e.g. c:\program files\oxdoc\bin);
2. the current working directory.

It is a good idea to put computer-specific settings in the bin directory and project-specific settings in project directories.

4.2. Lay-out of oxdoc.xml

<oxdoc>
	<option name="latex"     value="c:\texmf\miktex\bin\latex.exe" />
	<option name="dvipng"    value="c:\texmf\miktex\bin\dvipng.exe" />
	<option name="tempdir"   value="c:\temp\" />
</oxdoc>

oxdoc -latex=c:\bin\latex.exe *.ox

At startup, oxdoc checks whether it can find the executables required for LaTeX support. If it can't find one or more of these executables, it automatically turns off LaTeX support. In that case, formulae are literally written in the output. Turning off LaTeX support can also be done manually by setting the enablelatex setting to no.

It is also possible to specify extra LaTeX packages to be included within formulae. This can be done by specifying the desired packages, separated by commas, in the option latexpackages.

4.5. Overview of available settings