Lubyk documentation

Documentation extractor

lut.Doc parses lua comments and extracts the documentation from these comments. For usage, see lut.Doc.new.

It parses indifferently multiline comments like this:

--[[ 
Some text in comments.

Some more text.
--]]

and single line comments like this:

-- Some text in comments.
-- 
-- Some more text.

Parsing modes

By using the special comment -- doc:[option], you can change how the parsing is done.

Literate programming

The parser can generate full script documentation with all lua code when set to "lit" (for literate). Turn this option off by setting "nolit".

-- doc:lit
-- This part is considered literate programming and all comments and lua
-- code will be shown in the documentation.
local x

doSomething(x)

-- doc:nolit
-- End of literate part: only the library "lib" will be documented.

Loose documentation

By setting -- doc:loose, the parser will generate a single TODO about missing documentation and will not generate any more TODO entries for each undocummented function or parameter.

Even if the function names look obvious while writing the code and documentation seems superfluous, users will usually appreciate some real phrases describing what the function does. Using "loose" is not a good idea but can make the documentation more readable if most of the functions are not documented.

Extraction

Function extraction

All functions and methods defined against lib are extracted even if they are not yet documented. Example:

function lib:foo(a, b)
  -- Will generate a TODO with "MISSING DOCUMENTATION"
end

-- Documented function.
function lib:bar()
end

-- Documented class function.
function lib.boom()
end

If a function definition does not follow this convention, it can be documented with a commented version of the function definition:

-- Special function declaration.
-- function lib:bing(a, b, c)
lib.bing = lut.Doc.bang

-- Out of file function definition (in C++ for example).
-- function lib:connect(server)

-- Out of file constant definition
-- lib.Default

To ignore functions, use -- nodoc as documentation:

-- nodoc
function lib:badOldLegacyFunction(x, y)
end

Table parameters

All parameters defined against lib are documented unless -- nodoc is used.

lib.foo = 4
lib.bar = 5

-- nodoc
lib.old_foo = 4

Since Lua is also used as a description language, it is often useful to document table keys. This is done by using -- doc. It is a good idea to create a new for each table in order to document the table itself.

The parsed parameters for table 'key' is stored in doc.params[key] in parsing order. In the following example, this is doc.params.ATTRIBS.

-- This is an example of attributes documentation.

local ATTRIBS = { -- doc
  -- Documentation on first key.
  first_name = '',

  -- Documentation on second key.
  last_name = '',

  -- ## Sub-title
  -- Some text for this group of attributes.

  phone = {default = '', format = '000 000 00 00'},

  -- Documentation of element in list
  'lua ~> 5.1',

  -- Other element
  'lub ~> 1.0',
}

Such a list will create the following documentation:

Attributes (example)

This is an example of attributes documentation.

ATTRIBS = {

first_name = ''

Documentation on first key.

last_name = ''

Documentation on second key.

Sub-title

phone = {default = '', format = '000 000 00 00'}

'lua ~> 5.1'

Documentation of element in list

'lub ~> 1.0'

Other element

}

Preamble

You must start your file with a preample containing a title for the class or module and some description.

--[[---------------------------------------
  
  # Full title for the file/class

  This first paragraph is the summary.

  Some more description.

--]]---------------------------------------

Math

The [math] tag can be used to generate mathematics from latex code. When outputing html, the page uses MathJax when outputing html. Here is an example of mathematics inline and as standalone paragraph:

-- Some documentation with inline
-- [math]\gamma[/math] math. And now a
-- standalone math paragraph:
--
-- [math]\frac{\partial}{\partial\theta_j}J(\theta) = \frac{1}{m}\sum_{i=1}^m(\theta^{T}x^{(i)}-y^{(i)})x_j^{(i)}[/math]

The result for the code above is:

Some documentation with inline \(\gamma\) math. And now a standalone math paragraph:

\(\frac{\partial}{\partial\theta_j}J(\theta) = \frac{1}{m}\sum_{i=1}^m(\theta^{T}x^{(i)}-y^{(i)})x_j^{(i)}\)

If you hover with the mouse over the formula, it zooms.

Lua code

You can insert code snippets by indenting the code with two spaces. Here is an example of some normal text and some Lua and C++ code.

--[[
Some Lua code:

  local foo = {}
  -- print something
  print 'Hello'

And a cpp example:

  #cpp
  float x = 1.0;
  printf("Result = %.2f\n", x);
--]]

This results in:

Some Lua code:

local foo = {}
-- print something
print 'Hello'

And a cpp example:

float x = 1.0;
printf("Result = %.2f\n", x);

As you can see, you have to declare other languages with #name if the code is not Lua. When using #txt, the code is not styled with prettyprint. The code lang can also contain multiple words. The first word is the language and the following are used for CSS class styling.

Special ascii art code:

+--------+
| a box  |
+--------+

Styles, links

You can enhance your comments with links, bold, italics and images.

Some links are automatically created when the parser sees module.Class like this lut.Doc or #Some-local-id. A custom link is made with [link title](http://example.com).

Bold is done by using stars: some text with *bold* emphasis. Italics are inserted with underscores: some text _with italic_ emphasis.

You can add images with ![alt text](/path/to/image.jpg).

Inline code is inserted with backticks:

-- This is `inline code`.

You can also insert raw html with <html> tag.

<html><a href='example.com'>hello</a></html>

Lists

There are two kinds of lists available. The first one is simply a bullet list:

* First element
* Second element with more text
  that wraps around
* Third

Which renders as:

• First element
• Second element with more text that wraps around
• Third

The second style is for definitions:

+ some key:       is used to do something.
+ other long key: is used with a very long definition that
                  wraps around and even more text that goes
                  beyond.
+ `last key`:     is a code key.

Renders as:

Special paragraphs

You can create special paragraphs by starting them with one of the special keywords in upercase: TODO, FIXME, WARN, NOTE.

TODO This is a todo definition

FIXME This is a fixme

NOTE This paragraph is a note.

WARN This is a warning.

These end up like this (todo and fixme are repeated at the end of the file, but not for this example).

TODO This is a todo definition

FIXME This is a fixme

NOTE This paragraph is a note.

WARN This is a warning.

.ASSETS = {

nodoc list of files to copy in generated documentation.

Class functions

.new (path, def)

Parse the content of a file given by path and return an lut.Doc object containing the documentation of the class.

Usage example:

require 'lut'
local doc = lut.Doc('path/to/File.lua', {target = 'doc'})
lub.writeall('doc/File.html', doc:toHtml())

When documenting multiple files it is better to use make.

Possible keys in def (all are optional if path is given):

.make (def)

Generate the documentation for multiple files.

The sources parameter lists paths to Lua files or directories to parse and document.

Usage:

require 'lut'
lut.Doc.make {
  sources = {
    'lib/doc/DocTest.lua',
    'lib/doc/Other.lua',
    {'doc', prepend = 'examples/foo'},
  },
  copy = { 'doc', prepend = 'examples/lens', filter = '%.lua' },
  target = 'doc',
  format = 'html',
  header = [[
    <a href='http://lubyk.org'>
      <img alt='lubyk logo' src='img/logo.png'/>
      <h1>Lubyk documentation</h1>
    </a>
  ]],
  footer = [[ made with <a href='lut.Doc.html'>lut.Doc</a> ]],
}

Methods

:toHtml (template)

Render the documentation as html. If a template is provided, it is used instead of the default one. This is mainly used for testing since you usually want to have some navigation menus which are extracted by creating the documentation in batch mode with make.

Table of contents