Aire-One
/
LDoc2tl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
LDoc2tl/docs/doc.md

618 lines
27 KiB
Markdown
Raw Blame History

## LDoc - A Lua Documentation Tool
LDoc follows the conventions established by Javadoc and later by LuaDoc.
Only 'doc comments' are parsed; these can be started with at least 3 hyphens, or by a empty comment line with at least 3 hypens:
--- summary.
-- Description; this can extend over
-- several lines
-----------------
-- This will also do.
You can also use Lua block comments:
--[[--
Summary. A description
..;
]]
Any module or script must start with a doc comment; any other files are ignored and a warning issued. The only exception is if the module starts with an explicit `module` statement.
All doc comments start with a summary sentence, that ends with a period or a question mark. An optional description may follow. Normally the summary sentence will appear in the module contents.
After this descriptive text, there will typically be _tags_. These follow the convention established by Javadoc and widely used in tools for other languages.
--- foo explodes text.
-- It is a specialized splitting operation on a string.
-- @param text the string
-- @return a table of substrings
function foo (text)
....
end
There may be multiple 'param' tags, which should document each formal parameter of the function. For Lua, there can also be multiple 'return' tags
--- solvers for common equations.
module("solvers", package.seeall)
--- solve a quadratic equation.
-- @param a first coeff
-- @param b second coeff
-- @param c third coeff
-- @return first root, or nil
-- @return second root, or imaginary root error
function solve (a,b,c)
local disc = b^2 - 4*a*c
if disc < 0 then
return nil,"imaginary roots"
else
disc = math.sqrt(disc)
return (-b + disc)/2*a,
(-b - disc)/2*a
end
end
...
This is the common module style used in Lua 5.1, but it's increasingly common to see less 'magic' ways of creating modules in Lua. Since `module` is deprecated in Lua 5.2, any future-proof documentation tool needs to handle these styles gracefully:
--- a test module
-- @module test
local test = {}
--- first test.
function test.one()
...
end
...
return test
Here the name of the module is explicitly given using the 'module' tag. If you leave this out, then LDoc will infer the name of the module from the name of the file and its relative location in the filesystem; this logic is also used for the `module(...)` idiom. (How this works and when you need to provide extra information is discussed later.)
It is common to use a local name for a module when declaring its contents. In this case the 'alias' tag can tell LDoc that these functions do belong to the module:
--- another test.
-- @module test2
-- @alias M
local M = {}
-- first test.
function M.one()
..
end
return M
`M` and `_M` are used commonly enough that LDoc will recognize them as aliases automatically, but 'alias' allows you to use any identifier.
LDoc tries to deduce the function name and the formal parameter names from examining the code after the doc comment. It also recognizes the 'unsugared' way of defining functions as explicit assignment to a variable:
--- second test.
M.two = function(...) ... end
Apart from exported functions, a module usually contains local functions. By default, LDoc does not include these in the documentation, but they can be enabled using the `--all` flag. They can be documented just like 'public' functions:
--- it's clear that boo is local from context.
local function boo(...) .. end
local foo
--- we need to give a hint here for foo
-- @local here
function foo(...) .. end
Modules can of course export tables and other values. The classic way to document a table looks like this:
--- a useful table of constants
-- @field alpha first correction
-- @field beta second correction
-- @field gamma fudge factor
-- @table constants
Here the kind of item is made explicit by the 'table' tag; tables have 'fields' in the same way as functions have parameters.
This can get tedious, so LDoc will attempt to extract table documentation from code:
--- a useful table of constants
M.constants = {
alpha = 0.23, -- first correction
beta = 0.443, -- second correction
gamma = 0.01 -- fudge factor
}
The rule followed here is `NAME = <table-constructor>`. If LDoc can't work out the name and type from the following code, then a warning will be issued, pointing to the file and location.
Another kind of module-level type is 'field', such as follows:
--- module version.
M._VERSION = '0.5'
That is, a module may contain exported functions, local functions, tables and fields.
When the code analysis would lead to the wrong type, you can always be explicit.
--- module contents.
-- @field _CONTENTS
M._CONTENTS = {constants=true,one=true,...}
The order of tags is not important, but as always, consistency is useful. Tags like 'param' and 'return' can be specified multiple times, whereas a type tag like 'function' can only occur once in a comment. The basic rule is that a single doc comment can only document one entity.
By default, LDoc will process any file ending in '.lua' or '.luadoc' in a specified directory; you may point it to a single file as well. A 'project' usually consists of many modules in one or more _packages_. The generated `index.html` will point to the generated documentation for each of these modules.
If only one module or script is documented for a project, then the `index.html` generated contains the documentation for that module, since an index pointing to one module would be redundant.
(If you want to document a script, there is a project-level type 'script' for that.) By default it will process any file ending in `.lua` or `.luadoc`.
## @see References
The tag 'see' is used to reference other parts of the documentation, and 'usage' can provide examples of use:
---------
-- split a string in two.
-- @param s the string
-- @param delim the delimiter (default space)
-- @return first part
-- @return second part
-- @usage local hello,world = split2("hello world")
-- @see split
funtion split2(s,delim) .. end
Here it's assumed that 'split' is a function defined in the same module. If you wish to link to a function in another module, then the reference has to be qualified.
The example at `tests/complex` shows how @see references are interpreted:
complex.util.parse
complex.convert.basic
complex.util
complex.display
complex
You may of course use the full name of a module or function, but can omit the top-level namespace - e.g. can refer to the module `util` and the function `display.display_that` directly. Within a module, you can directly use a function name, e.g. in `display` you can say `display_this`.
What applies to functions also applies to any module-level item like tables. New module-level items can be defined and they will work according to these rules.
If a reference is not found within the project, LDoc checks to see if it is a reference to a Lua standard function or table, and links to the online Lua manual. So references like 'table.concat' are handled sensibly.
References may be made inline using the `@{ref}` syntax. This may appear anywhere in the text, and is more flexible than @see. In particular, it provides one way to document the type of a parameter or return value when that type has a particular structure:
------
-- extract standard variables.
-- @param s the string
-- @return @{stdvars}
function extract_std(s) ... end
------
-- standard variables.
-- Use @{extract_std} to parse a string containing variables,
-- and @{pack_std} to make such a string.
-- @field length
-- @field duration
-- @field viscosity
-- @table stdvars
## Sections
LDoc supports _explicit_ sections. The need occurs when a module has a lot of functions that need to be put into logical sections.
--- File functions.
-- Useful utilities for opening foobar format files.
-- @section file
--- open a file
...
--- read a file
...
--- Encoding operations.
-- Encoding foobar output in different ways.
-- @section encoding
...
A section doc-comment has the same structure as a normal doc-comment; the summary is used as the new section title, and the description will be output at the start of the function details for that section.
In any case, sections appear under 'Contents' on the left-hand side. See the [winapi](http://stevedonovan.github.com/winapi/api.html) documentation for an example of how this looks.
Arguably a module writer should not write such very long modules, but it is not the job of the documentation tool to limit the programmer!
A specialized kind of section is `type`: it is used for documenting classes. The functions (or fields) within a type section are considered to be the methods of that class.
--- A File class.
-- @type File
....
--- get the modification time.
-- @return standard time since epoch
function File:mtime()
...
(In an ideal world, we would use the word 'class' instead of 'type', but this would conflict with the LuaDoc usage.)
## Differences from LuaDoc
LDoc only does 'module' documentation, so the idea of 'files' is redundant.
One added convenience is that it is easier to name entities:
------------
-- a simple module.
-- (LuaDoc)
-- @class module
-- @name simple
------------
-- a simple module.
-- (LDoc)
-- @module simple
This is because type names (like 'function', 'module', 'table', etc) can function as tags. LDoc also provides a means to add new types (e.g. 'macro') using a configuration file which can be shipped with the source. If you become bored with typing 'param' repeatedly then you can define an alias for it, such as 'p'. This can also be specified in the configuration file.
LDoc will also work with C/C++ files, since extension writers clearly have the same documentation needs as Lua module writers:
/***
Create a table with given array and hash slots.
@function createtable
@param narr initial array slots, default 0
@param nrec initial hash slots, default 0
@return the new table
*/
static int l_createtable (lua_State *L) {
....
LDoc does not pretend to understand C/C++, so in this case it is necessary to specify the name and type explicitly.
LDoc gives the documenter the option to use Markdown to parse the contents of comments.
## LDoc is Extensible
LDoc tries to be faithful to LuaDoc, but provides some extensions.
'@function zero_fun' is short for the common sequence '@class function \ @name zero_fun'. In general, any type ('function','table',etc) can be used as a tag:
--- zero function. Two new ldoc features here; item types
-- can be used directly as tags, and aliases for tags
-- can be defined in config.ld.
-- @function zero_fun
-- @p k1 first
-- @p k2 second
Here an alias for 'param' has been defined. If a file `config.ld` is found in the source, then it will be loaded as Lua data. For example, the configuration for the above module provides a title and defines an alias for 'param':
title = "testmod docs"
project = "testmod"
alias("p","param")
Extra tag types can be defined:
new_type("macro","Macros")
And then used as any other tag:
-----
-- A useful macro. This is an example of a custom 'kind'.
-- @macro first_macro
-- @see second_function
This will also create a new module section called 'Macros'.
## Inferring more from Code
The qualified name of a function will be inferred from any `function` keyword following the doc comment. LDoc goes further with code analysis, however.
Instead of:
--- first table.
-- @table one
-- @field A alpha
-- @field B beta
M.one = {
A = 1,
B = 2;
}
you can write:
--- first table
-- @table one
M.one = {
A = 1, -- alpha
B = 2; -- beta
}
Simularly, function parameter comments can be directly used:
------------
-- third function. Can also provide parameter comments inline,
-- provided they follow this pattern.
function mod1.third_function(
alpha, -- correction A
beta, -- correction B
gamma -- factor C
)
...
end
## Supporting Extension modules written in C
LDoc can process C/C++ files:
/***
Create a table with given array and hash slots.
@function createtable
@param narr initial array slots, default 0
@param nrec initial hash slots, default 0
@return the new table
*/
static int l_createtable (lua_State *L) {
....
Both `/**` and `///` are recognized as starting a comment block. Otherwise, the tags are processed in exactly the same way. It is necessary to specify that this is a function with a given name, since this cannot be reliably be inferred from code.
An unknown extension can be associated with a language using a call like `add_language_extension('lc','c')` in `config.ld`. (Currently the language can only be 'c' or 'lua'.)
See 'tests/examples/mylib.c' for the full example.
## Basic Usage
The command-line options are:
ldoc, a documentation generator for Lua, vs 0.5
-d,--dir (default docs) output directory
-o,--output (default 'index') output name
-v,--verbose verbose
-a,--all show local functions, etc, in docs
-q,--quiet suppress output
-m,--module module docs as text
-s,--style (default !) directory for style sheet (ldoc.css)
-l,--template (default !) directory for template (ldoc.ltp)
-1,--one use one-column output layout
-p,--project (default ldoc) project name
-t,--title (default Reference) page title
-f,--format (default plain) formatting - can be markdown or plain
-b,--package (default .) top-level package basename (needed for module(...))
-x,--ext (default html) output file extension
-c,--config (default config.ld) configuration name
--dump debug output dump
--filter (default none) filter output as Lua data (e.g pl.pretty.dump)
<file> (string) source file or directory containing source
For example, to process all files in the 'lua' directory:
$ ldoc lua
output written to docs/
Thereafter the `docs` directory will contain `index.html` which points to individual modules in the `modules` subdirectory. The `--dir` flag can specify where the output is generated, and will ensure that the directory exists. The output structure is like LuaDoc: there is an `index.html` and the individual modules are in the `modules` subdirectory.
If your modules use `module(...)` then the module name has to be deduced. If `ldoc` is run from the root of the package, then this deduction does not need any help - e.g. if your package was `foo` then `ldoc foo` will work as expected. If we were actually in the `foo` directory then `ldoc -b .. .` will correctly deduce the module names. Another example would be generating documentation for LuaDoc itself:
$ ldoc -b .. /path/to/luadoc
Without the `-b` setting the base of the package to the _parent_ of the directory, then implicit modules like `luadoc.config` will be incorrectly placed in the global namespace.
For new-style modules, that don't use `module()`, it is recommended that the module comment has an explicit `@module PACKAGE.NAME`. If it does not, then `ldoc` will still attempt to deduce the module name, but may need help with `--package/-b` as above.
It is common to use an alias for the package name with new-style modules. Here an alias is explicitly specified, so that `ldoc` knows that functions qualified with `A` are part of the module `simple_alias`:
------------
-- A new-style module.
-- @alias A
local simple_alias = {}
local A = simple_alias
--- return the answer. And complete the description
function A.answer()
return 42
end
return simple_alias
(Here the actual module name is deduced from the file name, just like with `module(...)`)
It's semi-standard to use 'M' or '_M' for the module alias; LDoc will recognize these automatically.
This requires [markdown.lua](http://www.frykholm.se/files/markdown.lua) by Niklas Frykholm to be installed (this can be most easily done with `luarocks install markdown`.) `format = 'markdown'` can be used in your `config.ld`.
A special case is if you simply say 'ldoc .'. Then there _must_ be a `config.ld` file available in the directory, and it can specify the file:
file = "mymod.lua"
title = "mymod documentation"
description = "mymod does some simple but useful things"
`file` can of course point to a directory, just as with the `--file` option. This mode makes it particularly easy for the user to build the documentation, by allowing you to specify everything explicitly in the configuration.
## Processing Single Modules
`--output` can be used to give the output file a different name. This is useful for the special case when a single module file is specified. Here an index would be redundant, so the single HTML file generated contains the module documentation.
$ ldoc mylib.lua --> results in docs/index.html
$ ldoc --output mylib mylib.lua --> results in docs/mylib.html
$ ldoc --output mylib --dir html mylib.lua --> results in html/mylib.html
The default sections used by LDoc are 'Functions', 'Tables' and 'Fields', corresponding to the built-in types 'function', 'table' and 'field'. If `config.ld` contains something like `new_type("macro","Macros")` then this adds a new section 'Macros' which contains items of 'macro' type - 'macro' is registered as a new valid tag name. The default template then presents items under their corresponding section titles, in order of definition.
## Dumping and getting Help about a Module
There is an option to simply dump the results of parsing modules. Consider the C example `tests/example/mylib.c':
$ ldoc --dump mylib.c
----
module: mylib A sample C extension.
Demonstrates using ldoc's C/C++ support. Can either use /// or /*** */ etc.
function createtable(narr, nrec)
Create a table with given array and hash slots.
narr initial array slots, default 0
nrec initial hash slots, default 0
function solve(a, b, c)
Solve a quadratic equation.
a coefficient of x^2
b coefficient of x
c constant
return {"first root","second root"}
This is useful to quickly check for problems; here we see that `createable` did not have a return tag.
There is a more customizable way to process the data, using the `--filter` parameter. This is understood to be a fully qualified function (module + name). For example, try
$ ldoc --filter pl.pretty.dump mylib.c
to see a raw dump of the data. (Simply using `dump` here would be a shorthand for `pl.pretty.dump`.)
LDoc takes this idea of data dumping one step further. If used with the `-m` flag it will look up an installed Lua module and parse it. If it has been marked up in LuaDoc-style then you will get a handy summary of the contents:
$ ldoc -m pl.pretty
----
module: pl.pretty Pretty-printing Lua tables.
* read(s) - read a string representation of a Lua table.
* write(tbl, space, not_clever) - Create a string representation of a Lua table.
* dump(t, ...) - Dump a Lua table out to a file or stdout.
You can specify a fully qualified function to get more information:
$ ldoc -m pl.pretty.write
function write(tbl, space, not_clever)
create a string representation of a Lua table.
tbl {table} Table to serialize to a string.
space {string} (optional) The indent to use.
Defaults to two spaces.
not_clever {bool} (optional) Use for plain output, e.g {['key']=1}.
Defaults to false.
LDoc knows about the basic Lua libraries, so that it can be used as a handy console reference:
$> ldoc -m assert
function assert(v, message)
Issues an error when the value of its argument `v` is false (i.e.,
nil or false); otherwise, returns all its arguments.
`message` is an error
message; when absent, it defaults to "assertion failed!"
v
message
Thanks to mitchell's [TextAdept](http://code.google.com/p/textadept/) project, LDoc has a set of `.luadoc` files for all the standard tables, plus [LuaFileSystem](http://keplerproject.github.com/luafilesystem/) and [LPeg](http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html).
$> ldoc -m lfs.lock
function lock(filehandle, mode, start, length)
Locks a file or a part of it.
This function works on open files; the file
handle should be specified as the first argument. The string mode could be
either r (for a read/shared lock) or w (for a write/exclusive lock). The
optional arguments start and length can be used to specify a starting point
and its length; both should be numbers.
Returns true if the operation was successful; in case of error, it returns
nil plus an error string.
filehandle
mode
start
length
## Anatomy of a LDoc-generated Page
[winapi](http://stevedonovan.github.com/winapi/api.html) can be used as a good example of a module that uses extended LDoc features.
The _navigation section_ down the left has several parts:
# The project name (`project' in the config)
# A project description ('description')
# ''Contents'' of the current page
# ''Modules'' listing all the modules in this project
Note that `description` will be passed through Markdown, if it has been specified for the project. This gives you an opportunity to make lists of links, etc; any '##' headers will be formatted like the other top-level items on the navigation bar.
'Contents' is automatically generated. It will contain any explicit sections, if they have been used. Otherwise you will get the usual categories: 'Functions' and 'Tables'.
'Modules' will appear for any project providing Lua libraries; there may also be a 'Scripts' section if the project contains Lua scripts. For example, [LuaMacro](http://stevedonovan.github.com/LuaMacro/docs/api.html) has a driver script `luam` in this section. The [builtin](http://stevedonovan.github.com/LuaMacro/docs/modules/macro.builtin.html) module only defines macros, which are defined as a [custom tag type](!).
## Including source examples and a readme file
It has been long known that documentation generated just from the source is not really adequate to explain _how_ to use a library. People like reading narrative documentation, and they like looking at examples. Previously I found myself dealing with source-generated and writer-generated documentation using different tools, and having to match these up.
LDoc allows for source examples to be included in the documentation. For example, see the online documentation for [winapi](http://stevedonovan.github.com/winapi/api.html). The function `utf8_expand` has a @see reference to 'testu.lua' and following that link gives you a pretty-printed version of the code.
The line in the `config.ld` that enables this is:
examples = {'examples', exclude = {'examples/slow.lua'}}
That is, all files in the `examples` folder are to be pretty-printed, except for `slow.lua` which is meant to be called from one of the examples. The see-reference to `testu.lua` resolves to 'examples/testu.lua.html'.
Examples may link back to the API documentation, for instance the example `input.lua` has a `@{spawn_process}` inline reference.
Like all good Github projects, Winapi has a `readme.md`:
readme = "readme.md"
This goes under the 'Topics' global section; the 'Contents' of this document is generated from the second-level (##) headings of the readme.
Readme files are always processed with Markdown, but may also contain `@{}` references back to the documentation and to example files. As with doc comments, a link to a standard Lua function like @{os.execute}` will work as well. Any code sections will be pretty-printed as well; this may be not want you want, so if the first line of an indented code block is '@nocode' then that block will not be pretty-printed.
## Fields allowed in `config.ld`
These mostly have the same meaning as the corresponding parameters:
- `file` a file or directory containing sources. In `config.ld` this can also be a table of files and directories.
- `project` name of project, used as title in top left
- `title` page title, default 'Reference'
- `package`
- `all` show local functions, etc as well in the docs
- `format` markup processor, can be 'none' (default) or 'markdown'
- `output` output name (default 'index')
- `dir` directory for output files (default 'docs')
- `ext` extension for output (default 'html')
- `one` use a one-column layout
- `style`, `template` together these specify the directories for the style and and the template. In `config.ld` they may also be `true`, meaning use the same directory as the configuration file.
These only appear in `config.ld`:
- `description` a project description used under the project title
- `examples` a directory or file: can be a table
- `readme` name of readme file (to be processed with Markdown)
Available functions are:
- `alias(a,tag)` provide an alias `a` for the tag `tag`, for instance `p` as short for `param`
- `add_language_extension(ext,lang)` here `lang` may be either 'c' or 'lua', and `ext` is an extension to be recognized as this language
- `add_section`
- `new_type(tag,header,project_level)` used to add new tags, which are put in their own section `header`. They may be 'project level'.
## Generating HTML
LDoc, like LuaDoc, generates output HTML using a template, in this case `ldoc.ltp`. This is expanded by the powerful but simple preprocessor devised originally by [Rici Lake](http://lua-users.org/wiki/SlightlyLessSimpleLuaPreprocessor) which is now part of Penlight. There are two rules - any line starting with '#' is Lua code, which can also be embedded with '$(...)'.
<h2>Contents</h2>
<ul>
# for kind,items in module.kinds() do
<li><a href="#$(no_spaces(kind))">$(kind)</a></li>
# end
</ul>
This is then styled with `ldoc.css`. Currently the template and stylesheet is very much based on LuaDoc, so the results are mostly equivalent; the main change that the template has been more generalized. The default location (indicated by '!') is the directory of `ldoc.lua`.
You may customize how you generate your documentation by specifying an alternative style sheet and/or template, which can be deployed with your project. The parameters are `--style` and `--template`, which give the directories where `ldoc.css` and `ldoc.ltp` are to be found. If `config.ld` contains these variables, they are interpreted slightly differently; if they are true, then it means 'use the same directory as config.ld'; otherwise they must be a valid directory relative to the ldoc invocation. An example of fully customized documentation is `tests/example/style': this is what you could call 'minimal Markdown style' where there is no attempt to tag things (except emphasizing parameter names). The narrative ought to be sufficient, if it is written appropriately.
Of course, there's no reason why LDoc must always generate HTML. `--ext' defines what output extension to use; this can also be set in the configuration file. So it's possible to write a template that converts LDoc output to LaTex, for instance.
Reference in New Issue View Git Blame Copy Permalink