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
Oldot is a command line tool; invoke it as follows:
oldot <options> <sourcefiles...>
Use --help
to get a summary of the options. These include:
--output
<directory>--summary
<url>--title
<text>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.
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:
-
or +
, it is assumed to be a method on the current class;.
, it is assumed to be a fully qualified class name;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).
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.