Lubyk documentation

Documentation extractor

lk.Doc parses lua comments and extracts the documentation from these comments.

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 = lk.Doc.bang

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

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.

-- # Attributes (example)
-- 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'},
}

Such a list will create the following documentation:

Attributes (example)

This is an example of attributes documentation.

.first_name = ''

Documentation on first key.

.last_name = ''

Documentation on second key.

Sub-title

Some text for this group of attributes.

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

Usage

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.

Styles

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

Some links are automatically created when the parser sees module.Class like this: lk.Doc. 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`.

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:

TODO and FIXME

You can create TODO and FIXME marks like this

TODO This is a todo definition

FIXME This is a fixme

These end up like this (and are repeated at the end of the file).

TODO This is a todo definition

FIXME This is a fixme

Class functions

.new (path, def)

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

Usage example:

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

When documenting multiple files it is better to use make.

The navigation and children tables are used to display the navigation menu on the right and class list in the document body.

.make (def)

Generate the documentation for multiple files.

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

Usage:

require 'lubyk'
lk.Doc.make {
  sources = {
    'lib/doc/DocTest.lua',
    'lib/doc/Other.lua',
    {'doc', prepend = 'tutorial/foo'},
  },
  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='lk.Doc.html'>lk.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.

TODO

UsageTODO This is a todo definition

FIXME

UsageFIXME This is a fixme