Oldot (the Objective Lua Documentation Tool)

Introduction

Oldot is a tool for generating class API documentation from Objective Lua source code, reading text from specially formatted comments.

Oldot makes extensive use of Markdown text formatting. See the Markdown website for syntax information:

The main Markdown reference page

Usage

Oldot is a command line tool; invoke it as follows:

oldot <options> <sourcefiles...>

Use --help to get a summary of the options. These include:

Comment syntax

Oldot comments always start with ---. Such a comment placed before an Objective Lua syntax element (such as a class or method definition) contain the documentation for that element.

--- I am a sample class.
-- This line is ignored by Oldot.

@implementation SampleClass : olua.lib.Object
@end

Comments contain Markdown syntax.

--- I am a sample class.
---
--- This is another paragraph, containing *italics* or `code`.
--- It can also contain <u>inline HTML</u>.
---
--- * This is the first item of a list.
--- * And this is the second.
---
---     This is inline code. Note that is has to be indented
---     by *five* spaces (4 for markdown and 1 for Oldot).

Comments can also contain special sequences that are expanded by Oldot.

Note that currently only the documentation for the main category of a class is shown.

@ref

The @ref() keywords produces a hyperlink to an Objective Lua class or method.

--- Please see @ref(olua.lib.Object>>+alloc) for more information.

This refers to the +alloc method of olua.lib.Object.

You may omit extraneous information and Oldot will attempt to guess what you mean:

--- You need to pass an instance of @ref(Baseclass) into the
--- @ref(fnord) method.

The rules are:

Method declarations

The @param and @return keywords allow documentation of method arguments and return values.

--- This method chucks wood.
---
--- @param kind     what kind of wood
--- @param amount   how much wood to chuck
--- @return         the actual amount of wood chucked

- chuckWoodOfKind: kind andAmount: amount
do
    ...
end

The first word of @param must refer to a named parameter of the method definition. The rest of the line becomes the documentation (and is processed normally by Markdown).

Problems

Oldot is under development and contains a number of bugs, particularly related to invalid input. I recommend making sure your code compiles before running Oldot on it.

Right now Oldot can't cope with unhandled dependencies. This means that you must pass in all source your program depends on along with your program's source --- including the Objective Lua runtime. This rather limits its value outside of Objective Lua maintenance.

There's no way to prevent Oldot from documenting a method or class, which means that you can't distinguish between internal methods and public methods; you have to put at least some documentation in, otherwise you end up with an empty method declaration.

Oldot only knows about Objective Lua syntax. You can't document pure Lua code, which means you can't document global functions.