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

updated 1.3 docs

This commit is contained in:
steve donovan 2012-12-29 11:59:30 +02:00
parent b039ac1574
commit 7e53497393
2 changed files with 431 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

510
docs/doc.md
View File

@ -2,21 +2,38 @@
## Introduction ## Introduction
LDoc is a second-generation documentation tool that can be used as a replacement for [LuaDoc](http://keplerproject.github.com/luadoc/). It arose out of my need to document my own projects and only depends on the [Penlight](https://github.com/stevedonovan/Penlight) libraries. LDoc is a second-generation documentation tool that can be used as a replacement for
[LuaDoc](http://keplerproject.github.com/luadoc/). It arose out of my need to document my
own projects and only depends on the [Penlight](https://github.com/stevedonovan/Penlight)
libraries.
It is mostly compatible with LuaDoc, except that certain workarounds are no longer needed. For instance, it is not so married to the idea that Lua modules should be defined using the `module` function; this is not only a matter of taste since this has been deprecated in Lua 5.2. It is mostly compatible with LuaDoc, except that certain workarounds are no longer needed.
For instance, it is not so married to the idea that Lua modules should be defined using the
`module` function; this is not only a matter of taste since this has been deprecated in Lua
5.2.
Otherwise, the output is very similar, which is no accident since the HTML templates are based directly on LuaDoc. You can ship your own customized templates and style sheets with your [own project](http://nilnor.github.com/textui/docs/), however. You have an option to use Markdown to process the documentation, which means no ugly HTML is needed in doc comments. C/C++ extension modules may be documented in a similar way, although function names cannot be inferred from the code itself. Otherwise, the output is very similar, which is no accident since the HTML templates are
based directly on LuaDoc. You can ship your own customized templates and style sheets with
your [own project](http://nilnor.github.com/textui/docs/), however. You have an option to
use Markdown to process the documentation, which means no ugly HTML is needed in doc
comments. C/C++ extension modules may be documented in a similar way, although function
names cannot be inferred from the code itself.
LDoc can provide integrated documentation, with traditional function comments, any documents in Markdown format, and specified source examples. Lua source in examples and the documents will be prettified. LDoc can provide integrated documentation, with traditional function comments, any documents
in Markdown format, and specified source examples. Lua source in examples and the documents
will be prettified.
Although there are a fair number of command-line options, the preferred route is to write a `config.ld` configuration file in Lua format. By convention, if LDoc is simply invoked as `ldoc .` it will read this file first. In this way, the aim is to make it very easy for end-users to build your documentation using this simple command. Although there are a fair number of command-line options, the preferred route is to write a
`config.ld` configuration file in Lua format. By convention, if LDoc is simply invoked as
`ldoc .` it will read this file first. In this way, the aim is to make it very easy for
end-users to build your documentation using this simple command.
## Commenting Conventions ## Commenting Conventions
LDoc follows the conventions established by Javadoc and later by LuaDoc. 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: 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. --- summary.
-- Description; this can extend over -- Description; this can extend over
@ -32,11 +49,16 @@ You can also use Lua block comments:
...; ...;
]] ]]
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. 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. 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. 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. --- foo explodes text.
-- It is a specialized splitting operation on a string. -- It is a specialized splitting operation on a string.
@ -51,7 +73,8 @@ There are also 'tparam' and 'treturn' which let you [specify a type](#Tag_Modifi
-- @tparam string text the string -- @tparam string text the string
-- @treturn {string,...} a table of substrings -- @treturn {string,...} a table of substrings
There may be multiple 'param' tags, which should document each formal parameter of the function. For Lua, there can also be multiple 'return' tags 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. --- solvers for common equations.
module("solvers", package.seeall) module("solvers", package.seeall)
@ -75,7 +98,9 @@ There may be multiple 'param' tags, which should document each formal parameter
... ...
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: 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 --- a test module
-- @module test -- @module test
@ -91,9 +116,13 @@ This is the common module style used in Lua 5.1, but it's increasingly common to
return test 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.) 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: 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. --- another test.
-- @module test2 -- @module test2
@ -108,14 +137,19 @@ It is common to use a local name for a module when declaring its contents. In th
return M 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. `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: 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. --- second test.
M.two = function(...) ... end 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: 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. --- it's clear that boo is local from context.
local function boo(...) .. end local function boo(...) .. end
@ -126,7 +160,8 @@ Apart from exported functions, a module usually contains local functions. By def
-- @local here -- @local here
function foo(...) .. end function foo(...) .. end
Modules can of course export tables and other values. The classic way to document a table looks like this: Modules can of course export tables and other values. The classic way to document a table
looks like this:
--- a useful table of constants --- a useful table of constants
-- @field alpha first correction -- @field alpha first correction
@ -134,7 +169,8 @@ Modules can of course export tables and other values. The classic way to documen
-- @field gamma fudge factor -- @field gamma fudge factor
-- @table constants -- @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. 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: This can get tedious, so LDoc will attempt to extract table documentation from code:
@ -145,7 +181,9 @@ This can get tedious, so LDoc will attempt to extract table documentation from c
gamma = 0.01 -- fudge factor 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. 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: Another kind of module-level type is 'field', such as follows:
@ -160,17 +198,26 @@ When the code analysis would lead to the wrong type, you can always be explicit.
-- @field _CONTENTS -- @field _CONTENTS
M._CONTENTS = {constants=true,one=true,...} 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. 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. 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 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.) (If you want to document a script, there is a project-level type 'script' for that.)
## See References ## See References
The tag 'see' is used to reference other parts of the documentation, and 'usage' can provide examples of use: The tag 'see' is used to reference other parts of the documentation, and 'usage' can provide
examples of use:
--------- ---------
-- split a string in two. -- split a string in two.
@ -182,9 +229,11 @@ The tag 'see' is used to reference other parts of the documentation, and 'usage'
-- @see split -- @see split
funtion split2(s,delim) .. end 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. 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.
References to methods use a colon: `myclass:method`; this is for instance how you would refer to members of a `@type` section. References to methods use a colon: `myclass:method`; this is for instance how you would
refer to members of a `@type` section.
The example at `tests/complex` shows how @see references are interpreted: The example at `tests/complex` shows how @see references are interpreted:
@ -194,13 +243,21 @@ The example at `tests/complex` shows how @see references are interpreted:
complex.display complex.display
complex 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`. 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. 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. 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: 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. -- extract standard variables.
@ -217,17 +274,57 @@ References may be made inline using the @\{ref} syntax. This may appear anywhere
-- @field viscosity -- @field viscosity
-- @table stdvars -- @table stdvars
@\{ref} is very useful for referencing your API from code samples and readme text. (I've had to throw in a spurious backspace to stop expansion in this example.) @\{ref} is very useful for referencing your API from code samples and readme text. (I've had
to throw in a spurious backspace to stop expansion in this example.)
The link text can be changed from the default by the extended syntax @\{ref|text}. The link text can be changed from the default by the extended syntax @\{ref|text}.
You can also put references in backticks, like `\`stdvars\``. This is commonly used in Markdown to indicate code, so it comes naturally when writing documents. It is controlled by the configuration variable `backtick_references`; the default is `true` if you use Markdown in your project, but can be specified explicitly in your `config.ld`. You can also put references in backticks, like `\`stdvars\``. This is commonly used in
Markdown to indicate code, so it comes naturally when writing documents. It is controlled by
the configuration variable `backtick_references`; the default is `true` if you use Markdown
in your project, but can be specified explicitly in your `config.ld`.
### Custom @see References
It's useful to define how to handle references external to a project. For instance, in the
[luaposix](https://github.com/luaposix/luaposix) project we wanted to have `man` references
to the corresponding C function:
------------
-- raise a signal on this process.
-- @see raise(3)
-- @int nsig
-- @return integer error cod
function raise (nsig)
end
These see references always have this particular form, and the task is to turn them into
online references to the Linux manpages. So in `config.ld` we have:
local upat = "http://www.kernel.org/doc/man-pages/online/pages/man%s/%s.%s.html"
custom_see_handler('^(%a+)%((%d)%)$',function(name,section)
local url = upat:format(section,name,section)
local name = name .. '(' ..section..')'
return name, url
end)
'^(%a+)%((%d)%)$' both matches the pattern and extracts the name and its section. THen it's
a simple matter of building up the appropriate URL. The function is expected to
return _link text_ and _link source_ and the patterns are checked before LDoc tries to resolve
project references. So it is best to make them match as exactly as possible.
## Sections ## Sections
LDoc supports _explicit_ sections. By default, the sections correspond to the pre-existing types in a module: 'Functions', 'Tables' and 'Fields' (There is another default section 'Local Functions' which only appears if LDoc is invoked with the `--all` flag.) But new sections can be added; the first mechanism is when you define a new type (say 'macro') a new section ('Macros') is created to contain these types. There is also a way to declare ad-hoc sections using the `@section` tag. LDoc supports _explicit_ sections. By default, the sections correspond to the pre-existing
types in a module: 'Functions', 'Tables' and 'Fields' (There is another default section
'Local Functions' which only appears if LDoc is invoked with the `--all` flag.) But new
sections can be added; the first mechanism is when you define a new type (say 'macro') a new
section ('Macros') is created to contain these types. There is also a way to declare ad-hoc
sections using the `@section` tag.
The need occurs when a module has a lot of functions that need to be put into logical sections. The need occurs when a module has a lot of functions that need to be put into logical
sections.
--- File functions. --- File functions.
-- Useful utilities for opening foobar format files. -- Useful utilities for opening foobar format files.
@ -245,13 +342,19 @@ The need occurs when a module has a lot of functions that need to be put into lo
... ...
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. 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. 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! 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 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. --- A File class.
-- @type File -- @type File
@ -263,11 +366,21 @@ A specialized kind of section is `type`: it is used for documenting classes. The
... ...
end end
(In an ideal world, we would use the word 'class' instead of 'type', but this would conflict with the LuaDoc usage.) (In an ideal world, we would use the word 'class' instead of 'type', but this would conflict
with the LuaDoc usage.)
A section continues until the next section is found, `@section end`, or end of file. A section continues until the next section is found, `@section end`, or end of file.
You can put items into an implicit section using the @within tag. This allows you to put
adjacent functions in different sections, so that you are not forced to order your code
in a particular way.
Sometimes a module may logically span several files. There will be a master module with name
'foo' and other files which when required add functions to that module. If these files have
a @submodule tag, their contents will be placed in the master module documentation. However,
a current limitation is that the master module must be processed before the submodules.
See the `tests/submodule` example for how this works in practice.
## Differences from LuaDoc ## Differences from LuaDoc
@ -286,15 +399,20 @@ One added convenience is that it is easier to name entities:
-- (LDoc) -- (LDoc)
-- @module simple -- @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. 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. LDoc will also work with C/C++ files, since extension writers clearly have the same
documentation needs as Lua module writers.
LDoc gives the documenter the option to use Markdown to parse the contents of comments. LDoc gives the documenter the option to use Markdown to parse the contents of comments.
## Adding new Tags ## Adding new Tags
LDoc tries to be faithful to LuaDoc, but provides some extensions. Aliases for tags can be defined, and new types declared. LDoc tries to be faithful to LuaDoc, but provides some extensions. Aliases for tags can be
defined, and new types declared.
--- zero function. Two new ldoc features here; item types --- zero function. Two new ldoc features here; item types
-- can be used directly as tags, and aliases for tags -- can be used directly as tags, and aliases for tags
@ -303,7 +421,9 @@ LDoc tries to be faithful to LuaDoc, but provides some extensions. Aliases for t
-- @p k1 first -- @p k1 first
-- @p k2 second -- @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': 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" title = "testmod docs"
project = "testmod" project = "testmod"
@ -324,7 +444,8 @@ This will also create a new module section called 'Macros'.
## Inferring more from Code ## 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 this kind of code analysis, however. The qualified name of a function will be inferred from any `function` keyword following the
doc comment. LDoc goes further with this kind of code analysis, however.
Instead of: Instead of:
@ -376,9 +497,14 @@ LDoc can process C/C++ files:
static int l_createtable (lua_State *L) { 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. Such a file will need a module comment, which is treated exactly as in Lua. 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. Such a file will need a
module comment, which is treated exactly as in Lua.
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'.) 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. See 'tests/examples/mylib.c' for the full example.
@ -389,42 +515,93 @@ For example, to process all files in the 'lua' directory:
$ ldoc lua $ ldoc lua
output written to docs/ 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. This applies to all project-level types, so that you can also get `scripts`, `examples` and `topics` directories. 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. This applies to
all project-level types, so that you can also get `scripts`, `examples` and `topics`
directories.
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. An example would be generating documentation for LuaDoc itself: 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. An example would be
generating documentation for LuaDoc itself:
$ ldoc -b .. /path/to/luadoc $ ldoc -b .. /path/to/luadoc
Without the `-b` setting the base of the package to the _parent_ of the directory, implicit modules like `luadoc.config` will be incorrectly placed in the global namespace. Without the `-b` setting the base of the package to the _parent_ of the directory, 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. 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.
`format = 'markdown'` can be used in your `config.ld` and will be used to process summaries and descriptions. 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`.) A much faster alternative is [lua-discount](http://asbradbury.org/projects/lua-discount/) which you can use by setting `format` to 'discount' after installing using `luarocks install lua-discount`) The [discount](http://www.pell.portland.or.us/~orc/Code/discount/) Markdown processor additionally has more features than the pure Lua version, such as PHP-Extra style tables. As a special case, LDoc will fall back to using `markdown.lua` if it cannot find `discount`. `format = 'markdown'` can be used in your `config.ld` and will be used to process summaries
and descriptions. 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`.) A much faster alternative is
[lua-discount](http://asbradbury.org/projects/lua-discount/) which you can use by setting
`format` to 'discount' after installing using `luarocks install lua-discount`) The
[discount](http://www.pell.portland.or.us/~orc/Code/discount/) Markdown processor
additionally has more features than the pure Lua version, such as PHP-Extra style tables.
As a special case, LDoc will fall back to using `markdown.lua` if it cannot find `discount`.
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: `format = 'markdown'` can be used in your `config.ld` and will be used to process summaries
and descriptions. This requires a markdown processor.
LDoc knows how to use:
- [markdown.lua](http://www.frykholm.se/files/markdown.lua) a pure Lua processor by
Niklas Frykholm (this can be installed easily with `luarocks install markdown`.)
- [lua-discount](http://asbradbury.org/projects/lua-discount/), a faster alternative
(installed with `luarocks install lua-discount`). lua-discount uses the C
[discount](http://www.pell.portland.or.us/~orc/Code/discount/) Markdown processor which has
more features than the pure Lua version, such as PHP-Extra style tables.
- [lunamark](http://jgm.github.com/lunamark/), another pure Lua processor, faster than
markdown, and with extra features (`luarocks install lunamark`).
You can request the processor you like with `format = 'markdown|discount|lunamark'`, and
LDoc will attempt to use it. If it can't find it, it will look for one of the other
markdown processors. If it can't find any markdown processer, it will fall back to text
processing.
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" file = "mymod.lua"
title = "mymod documentation" title = "mymod documentation"
description = "mymod does some simple but useful things" 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. `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.
In `config.ld`, `file` may be a Lua table, containing file names or directories; if it has an `exclude` field then that will be used to exclude files from the list, for example `{'examples', exclude = {'examples/slow.lua'}}`. In `config.ld`, `file` may be a Lua table, containing file names or directories; if it has
an `exclude` field then that will be used to exclude files from the list, for example
`{'examples', exclude = {'examples/slow.lua'}}`.
## Processing Single Modules ## 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. `--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 mylib.lua --> results in docs/index.html
$ ldoc --output mylib mylib.lua --> results in docs/mylib.html $ ldoc --output mylib mylib.lua --> results in docs/mylib.html
$ ldoc --output mylib --dir html mylib.lua --> results in html/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. 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.
## Getting Help about a Module ## 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': There is an option to simply dump the results of parsing modules. Consider the C example
`tests/example/mylib.c':
@plain @plain
$ ldoc --dump mylib.c $ ldoc --dump mylib.c
@ -444,9 +621,12 @@ There is an option to simply dump the results of parsing modules. Consider the C
c constant c constant
return {"first root","second root"} return {"first root","second root"}
This is useful to quickly check for problems; here we see that `createable` did not have a return tag. This is useful to quickly check for problems; here we see that `createable` did not have a
return tag.
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 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:
@plain @plain
$ ldoc -m pl.pretty $ ldoc -m pl.pretty
@ -483,7 +663,10 @@ LDoc knows about the basic Lua libraries, so that it can be used as a handy cons
v v
message 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). 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).
@plain @plain
$> ldoc -m lfs.lock $> ldoc -m lfs.lock
@ -504,7 +687,8 @@ Thanks to mitchell's [TextAdept](http://code.google.com/p/textadept/) project, L
## Anatomy of a LDoc-generated Page ## 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. [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 _navigation section_ down the left has several parts:
@ -513,11 +697,19 @@ The _navigation section_ down the left has several parts:
- ''Contents'' of the current page - ''Contents'' of the current page
- ''Modules'' listing all the modules in this project - ''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. 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', 'Tables' and 'Fields'. 'Contents' is automatically generated. It will contain any explicit sections, if they have
been used. Otherwise you will get the usual categories: 'Functions', 'Tables' and 'Fields'.
'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_. '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_.
The _content section_ on the right shows: The _content section_ on the right shows:
@ -525,13 +717,25 @@ The _content section_ on the right shows:
- The contents summary, per section as above - The contents summary, per section as above
- The detailed documentation for each item - The detailed documentation for each item
As before, the description can use Markdown. The summary contains the contents of each section as a table, with links to the details. This is where the difference between an item's summary and an item's description is important; the first will appear in the contents summary. The item details show the item name and its summary again, followed by the description. There are then sections for the following tags: 'param', 'usage', 'return' and 'see' in that order. (For tables, 'Fields' is used instead of 'Parameters' but internally fields of a table are stored as the 'param' tag.) As before, the description can use Markdown. The summary contains the contents of each
section as a table, with links to the details. This is where the difference between an
item's summary and an item's description is important; the first will appear in the contents
summary. The item details show the item name and its summary again, followed by the
description. There are then sections for the following tags: 'param', 'usage', 'return' and
'see' in that order. (For tables, 'Fields' is used instead of 'Parameters' but internally
fields of a table are stored as the 'param' tag.)
You can of course customize the default template, but there are some parameters that can control what the template will generate. Setting `one` to `true` in your configuration file will give a _one-column_ layout, which can be easier to use as a programming reference. You can suppress the contents summary with `no_summary`. You can of course customize the default template, but there are some parameters that can
control what the template will generate. Setting `one` to `true` in your configuration file
will give a _one-column_ layout, which can be easier to use as a programming reference. You
can suppress the contents summary with `no_summary`.
## Customizing the Page ## Customizing the Page
Setting `no_return_or_parms` to `true` will suppress the display of 'param' and 'return' tags. This may appeal to programmers who dislike the traditional @tag soup xDoc style and prefer to comment functions just with a description. This is particularly useful when using Markdown in a stylized way to specify arguments: Setting `no_return_or_parms` to `true` will suppress the display of 'param' and 'return'
tags. This may appeal to programmers who dislike the traditional @tag soup xDoc style and
prefer to comment functions just with a description. This is particularly useful when using
Markdown in a stylized way to specify arguments:
--------- ---------
-- This extracts the shortest common substring from the strings _s1_ and _s2_ -- This extracts the shortest common substring from the strings _s1_ and _s2_
@ -539,9 +743,13 @@ Setting `no_return_or_parms` to `true` will suppress the display of 'param' and
Here I've chosen to italicise parameter names; the main thing is to be consistent. Here I've chosen to italicise parameter names; the main thing is to be consistent.
This style is close to the Python [documentation standard](http://docs.python.org/library/array.html#module-array), especially when used with `no_summary`. This style is close to the Python [documentation
standard](http://docs.python.org/library/array.html#module-array), especially when used with
`no_summary`.
It is also very much how the Lua documentation is ordered. For instance, this configuration file formats the built-in documentation for the Lua global functions in a way which is close to the original: It is also very much how the Lua documentation is ordered. For instance, this configuration
file formats the built-in documentation for the Lua global functions in a way which is close
to the original:
project = 'Lua' project = 'Lua'
description = 'Lua Standard Libraries' description = 'Lua Standard Libraries'
@ -551,21 +759,33 @@ It is also very much how the Lua documentation is ordered. For instance, this co
format = 'discount' format = 'discount'
Generally, using Markdown gives you the opportunity to structure your documentation in any way you want; particularly if using lua-discount and its [table syntax](http://michelf.com/projects/php-markdown/extra/#table); the desired result can often be achieved then by using a custom style sheet. Generally, using Markdown gives you the opportunity to structure your documentation in any
way you want; particularly if using lua-discount and its [table
syntax](http://michelf.com/projects/php-markdown/extra/#table); the desired result can often
be achieved then by using a custom style sheet.
## Examples ## Examples
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. 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. 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: The line in the `config.ld` that enables this is:
examples = {'examples', exclude = {'examples/slow.lua'}} 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'. 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. Examples may link back to the API documentation, for instance the example `input.lua` has a
@\{spawn_process} inline reference.
## Readme files ## Readme files
@ -573,31 +793,69 @@ Like all good Github projects, Winapi has a `readme.md`:
readme = "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. 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. Any symbols within backticks will be expanded as references, if possible. 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 Lua, unless the first indented line is '@plain'. (See the source for this readme to see how it's used.) Readme files are always processed with Markdown, but may also contain @\{} references back
to the documentation and to example files. Any symbols within backticks will be expanded as
references, if possible. 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 Lua, unless
the first indented line is '@plain'. (See the source for this readme to see how it's used.)
Another name for `readme` is `topics`, which is more descriptive. From LDoc 1.2, `readme/topics` can be a list of documents. These act as a top-level table-of-contents for your documentation. Currently, if you want them in a particular order, then use names like `01-introduction.md` etc which sort appropriately. Another name for `readme` is `topics`, which is more descriptive. From LDoc 1.2,
`readme/topics` can be a list of documents. These act as a top-level table-of-contents for
your documentation. Currently, if you want them in a particular order, then use names like
`01-introduction.md` etc which sort appropriately.
The first line of a document may be a Markdown `#` title. If so, then LDoc will regard the next level as the subheadings, normally second-level `##`. But if the title is already second-level, then third-level headings will be used `###`, and so forth. The implication is that the first heading must be top-level relative to the headings that follow, and must start at the first line. The first line of a document may be a Markdown `#` title. If so, then LDoc will regard the
next level as the subheadings, normally second-level `##`. But if the title is already
second-level, then third-level headings will be used `###`, and so forth. The implication is
that the first heading must be top-level relative to the headings that follow, and must
start at the first line.
A reference like @\{string.upper} is unambiguous, and will refer to the online Lua manual. In a project like Penlight, it can get tedious to have to write out fully qualified names like @\{pl.utils.printf}. The first simplification is to use the `package` field to resolve unknown references, which in this case is 'pl'. (Previously we discussed how `package` is used to tell LDoc where the base package is in cases where the module author wishes to remain vague, but it does double-duty here.) A further level of simplification comes from the @lookup directive in documents, which must start at the first column on its own line. For instance, if I am talking about `pl.utils`, then I can say "@lookup utils" and thereafter references like @\{printf} will resolve correctly. A reference like @\{string.upper} is unambiguous, and will refer to the online Lua manual.
In a project like Penlight, it can get tedious to have to write out fully qualified names
like @\{pl.utils.printf}. The first simplification is to use the `package` field to resolve
unknown references, which in this case is 'pl'. (Previously we discussed how `package` is
used to tell LDoc where the base package is in cases where the module author wishes to
remain vague, but it does double-duty here.) A further level of simplification comes from
the @lookup directive in documents, which must start at the first column on its own line.
For instance, if I am talking about `pl.utils`, then I can say "@lookup utils" and
thereafter references like @\{printf} will resolve correctly.
Remember that the default is for references in backticks to be resolved; unlike @ references, it is not an error if the reference cannot be found. Remember that the default is for references in backticks to be resolved; unlike @
references, it is not an error if the reference cannot be found.
The _sections_ of a document (the second-level headings) are also references. This particular section can be refered to as @\{doc.md.Resolving_References_in_Documents} - the rule is that any non-alphabetic character is replaced by an underscore. The _sections_ of a document (the second-level headings) are also references. This
particular section can be refered to as @\{doc.md.Resolving_References_in_Documents} - the
rule is that any non-alphabetic character is replaced by an underscore.
## Tag Modifiers ## Tag Modifiers
New with this release is the idea of _tag modifiers_. For instance, you may say @\param[type=number] and this associates the modifier `type` with value `number` with this particular param tag. A shorthand can be introduced for this common case, which is "@tparam <type> <parmname> <comment>"; in the same way @\treturn is defined. Ay tag may have _tag modifiers_. For instance, you may say
@\param[type=number] and this associates the modifier `type` with value `number` with this
particular param tag. A shorthand can be introduced for this common case, which is "@tparam
<type> <parmname> <comment>"; in the same way @\treturn is defined.
This is useful for larger projects where you want to provide the argument and return value types for your API, in a structured way that can be easily extracted later. There is a useful function for creating new tags that can be used in `config.ld`: This is useful for larger projects where you want to provide the argument and return value
types for your API, in a structured way that can be easily extracted later. There is a
useful function for creating new tags that can be used in `config.ld`:
tparam_alias('string','string') tparam_alias('string','string')
That is, "@string" will now have the same meaning as "@tparam string". That is, "@string" will now have the same meaning as "@tparam string".
From 1.3, the following standard type aliases are predefined:
* `string`
* `number`
* `int`
* `bool` Lua 'boolean' type
* `func` 'function' (using 'function' would conflict with the type)
* `tab` 'table'
* `thread`
The exact form of `<type>` is not defined, but here is a suggested scheme: The exact form of `<type>` is not defined, but here is a suggested scheme:
number -- a plain type number -- a plain type
@ -608,17 +866,25 @@ The exact form of `<type>` is not defined, but here is a suggested scheme:
{[string]=Bonzo,...} -- a map of Bonzo objects with string keys {[string]=Bonzo,...} -- a map of Bonzo objects with string keys
Array(Bonzo) -- (assuming that Array is a container) Array(Bonzo) -- (assuming that Array is a container)
Currently the `type` modifier is the only one known and used by LDoc when generating HTML output. However, any other modifiers are allowed and are available for use with your own templates or for extraction by your own tools. Currently the `type` modifier is the only one known and used by LDoc when generating HTML
output. However, any other modifiers are allowed and are available for use with your own
templates or for extraction by your own tools.
The `alias` function within configuration files has been extended so that alias tags can be defined as a tag plus a set of modifiers. So `tparam` is defined as: The `alias` function within configuration files has been extended so that alias tags can be
defined as a tag plus a set of modifiers. So `tparam` is defined as:
alias('tparam',{'param',modifiers={type="$1"}}) alias('tparam',{'param',modifiers={type="$1"}})
As an extension, you're allowed to use '@param' tags in table definitions. This makes it
possible to use type alias like '@string' to describe fields, since they will expand to
'param'.
## Fields allowed in `config.ld` ## Fields allowed in `config.ld`
These mostly have the same meaning as the corresponding parameters: 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. - `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 - `project` name of project, used as title in top left
- `title` page title, default 'Reference' - `title` page title, default 'Reference'
- `package ` explicit base package name; also used for resolving references in documents - `package ` explicit base package name; also used for resolving references in documents
@ -628,7 +894,9 @@ These mostly have the same meaning as the corresponding parameters:
- `dir` directory for output files (default 'docs') - `dir` directory for output files (default 'docs')
- `ext` extension for output (default 'html') - `ext` extension for output (default 'html')
- `one` use a one-column layout - `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. - `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`: These only appear in `config.ld`:
@ -637,20 +905,27 @@ These only appear in `config.ld`:
- `readme` name of readme file (to be processed with Markdown) - `readme` name of readme file (to be processed with Markdown)
- `no_return_or_parms` don't show parameters or return values in output - `no_return_or_parms` don't show parameters or return values in output
- `backtick_references` whether references in backticks will be resolved - `backtick_references` whether references in backticks will be resolved
- `manual_url` point to an alternative or local location for the Lua manual, e.g. 'file:///D:/dev/lua/projects/lua-5.1.4/doc/manual.html' - `manual_url` point to an alternative or local location for the Lua manual, e.g.
'file:///D:/dev/lua/projects/lua-5.1.4/doc/manual.html'
Available functions are: Available functions are:
- `alias(a,tag)` provide an alias `a` for the tag `tag`, for instance `p` as short for `param` - `alias(a,tag)` provide an alias `a` for the tag `tag`, for instance `p` as short for
- `add_language_extension(ext,lang)` here `lang` may be either 'c' or 'lua', and `ext` is an extension to be recognized as this language `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` - `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'. - `new_type(tag,header,project_level)` used to add new tags, which are put in their own
- `tparam_alias(name,type)` for instance, you may wish that `string` means `@\tparam string`. section `header`. They may be 'project level'.
- `tparam_alias(name,type)` for instance, you may wish that `string` means `@\tparam
string`.
## Annotations and Searching for Tags ## Annotations and Searching for Tags
Annotations are special tags that can be used to keep track of internal development status. The known annotations are 'todo', 'fixme' and 'warning'. They may occur in regular function/table doc comments, or on their own anywhere in the code. Annotations are special tags that can be used to keep track of internal development status.
The known annotations are 'todo', 'fixme' and 'warning'. They may occur in regular
function/table doc comments, or on their own anywhere in the code.
--- Testing annotations --- Testing annotations
-- @module annot1 -- @module annot1
@ -664,7 +939,8 @@ Annotations are special tags that can be used to keep track of internal developm
--- @fixme what about else? --- @fixme what about else?
end end
Although not currently rendered by the template as HTML, they can be extracted by the `--tags` command, which is given a comma-separated list of tags to list. Although not currently rendered by the template as HTML, they can be extracted by the
`--tags` command, which is given a comma-separated list of tags to list.
@plain @plain
D:\dev\lua\LDoc\tests> ldoc --tags todo,fixme annot1.lua D:\dev\lua\LDoc\tests> ldoc --tags todo,fixme annot1.lua
@ -674,7 +950,11 @@ Although not currently rendered by the template as HTML, they can be extracted b
## Generating HTML ## Generating HTML
LDoc, like LuaDoc, generates output HTML using a template, in this case `ldoc_ltp.lua`. 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 '$(...)'. LDoc, like LuaDoc, generates output HTML using a template, in this case `ldoc_ltp.lua`. 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> <h2>Contents</h2>
<ul> <ul>
@ -683,21 +963,39 @@ LDoc, like LuaDoc, generates output HTML using a template, in this case `ldoc_lt
# end # end
</ul> </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`. 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. 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 alone _can_ to be sufficient, if it is written appropriately. 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 alone _can_ 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. The separation of processing and presentation makes this kind of new application possible with LDoc. 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. The separation of processing
and presentation makes this kind of new application possible with LDoc.
## Internal Data Representation ## Internal Data Representation
The `--dump` flag gives a rough text output on the console. But there is a more customizeable way to process the output data generated by LDoc, using the `--filter` parameter. This is understood to be a fully qualified function (module + name). For example, try The `--dump` flag gives a rough text output on the console. But there is a more
customizeable way to process the output data generated by LDoc, 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 $ ldoc --filter pl.pretty.dump mylib.c
to see a raw dump of the data. (Simply using `dump` as the value here would be a shorthand for `pl.pretty.dump`.) This is potentially very powerful, since you may write arbitrary Lua code to extract the information you need from your project. to see a raw dump of the data. (Simply using `dump` as the value here would be a shorthand
for `pl.pretty.dump`.) This is potentially very powerful, since you may write arbitrary Lua
code to extract the information you need from your project.
For instance, a file `custom.lua` like this: For instance, a file `custom.lua` like this:
@ -714,7 +1012,9 @@ Can be used like so:
~/LDoc/tests/example$ ldoc --filter custom.filter mylib.c ~/LDoc/tests/example$ ldoc --filter custom.filter mylib.c
module mylib A sample C extension. module mylib A sample C extension.
The basic data structure is straightforward: it is an array of 'modules' (project-level entities, including scripts) which each contain an `item` array (functions, tables and so forth). The basic data structure is straightforward: it is an array of 'modules' (project-level
entities, including scripts) which each contain an `item` array (functions, tables and so
forth).
For instance, to find all functions which don't have a @return tag: For instance, to find all functions which don't have a @return tag:
@ -730,8 +1030,12 @@ For instance, to find all functions which don't have a @return tag:
end end
} }
The internal naming is not always so consistent; `ret` corresponds to @return, and `params` corresponds to @param. `item.params` is an array of the function parameters, in order; it is also a map from these names to the individual descriptions of the parameters. The internal naming is not always so consistent; `ret` corresponds to @return, and `params`
corresponds to @param. `item.params` is an array of the function parameters, in order; it
is also a map from these names to the individual descriptions of the parameters.
`item.modifiers` is a table where the keys are the tags and the values are arrays of modifier tables. The standard tag aliases `tparam` and `treturn` attach a `type` modifier to their tags. `item.modifiers` is a table where the keys are the tags and the values are arrays of
modifier tables. The standard tag aliases `tparam` and `treturn` attach a `type` modifier
to their tags.

33
readme.md
View File

@ -1,14 +1,18 @@
# LDoc - A Lua Documentation Tool # LDoc - A Lua Documentation Tool
Copyright (C) 2011 Steve Donovan. Copyright (C) 2011-2012 Steve Donovan.
## Rationale ## Rationale
This project grew out of the documentation needs of [Penlight](https://github.com/stevedonovan/Penlight) (and not always getting satisfaction with LuaDoc) and depends on Penlight itself.(This allowed me to _not_ write a lot of code.) This project grew out of the documentation needs of
[Penlight](https://github.com/stevedonovan/Penlight) (and not always getting satisfaction
with LuaDoc) and depends on Penlight itself.(This allowed me to _not_ write a lot of code.)
The [API documentation](http://stevedonovan.github.com/Penlight/api/index.html) of Penlight is an example of a project using plain LuaDoc markup processed using LDoc. The [API documentation](http://stevedonovan.github.com/Penlight/api/index.html) of Penlight
is an example of a project using plain LuaDoc markup processed using LDoc.
LDoc is intended to be compatible with [LuaDoc](http://luadoc.luaforge.net/manual.htm) and thus follows the pattern set by the various *Doc tools: LDoc is intended to be compatible with [LuaDoc](http://luadoc.luaforge.net/manual.htm) and
thus follows the pattern set by the various *Doc tools:
--- Summary ends with a period. --- Summary ends with a period.
-- Some description, can be over several lines. -- Some description, can be over several lines.
@ -19,19 +23,30 @@ LDoc is intended to be compatible with [LuaDoc](http://luadoc.luaforge.net/manua
function mod1.first_fun(p1,p2) function mod1.first_fun(p1,p2)
end end
Tags such as `see` and `usage` are supported, and generally the names of functions and modules can be inferred from the code. Tags such as `see` and `usage` are supported, and generally the names of functions and
modules can be inferred from the code.
LDoc is designed to give better diagnostics: if a `@see` reference cannot be found, then the line number of the reference is given. LDoc knows about modules which do not use `module()` - this is important since this function has become deprecated in Lua 5.2. And you can avoid having to embed HTML in commments by using Markdown. LDoc is designed to give better diagnostics: if a `@see` reference cannot be found, then the
line number of the reference is given. LDoc knows about modules which do not use `module()`
- this is important since this function has become deprecated in Lua 5.2. And you can avoid
having to embed HTML in commments by using Markdown.
LDoc will also work with Lua C extension code, and provides some convenient shortcuts. LDoc will also work with Lua C extension code, and provides some convenient shortcuts.
An example showing the support for named sections and 'classes' is the [Winapi documentation](http://stevedonovan.github.com/winapi/api.html); this is generated from [winapi.l.c](https://github.com/stevedonovan/winapi/blob/master/winapi.l.c). An example showing the support for named sections and 'classes' is the [Winapi
documentation](http://stevedonovan.github.com/winapi/api.html); this is generated from
[winapi.l.c](https://github.com/stevedonovan/winapi/blob/master/winapi.l.c).
## Installation ## Installation
This is straightforward; the only external dependency is [Penlight](https://github.com/stevedonovan/Penlight), which in turn needs [LuaFileSystem](http://keplerproject.github.com/luafilesystem/). These are already present in Lua for Windows, and Penlight is also available through LuaRocks as `luarocks install penlight`. This is straightforward; the only external dependency is
[Penlight](https://github.com/stevedonovan/Penlight), which in turn needs
[LuaFileSystem](http://keplerproject.github.com/luafilesystem/). These are already present
in Lua for Windows, and Penlight is also available through LuaRocks as `luarocks install
penlight`.
Unpack the sources somewhere and make an alias to `ldoc.lua` on your path. That is, either an excutable script called 'ldoc' like so: Unpack the sources somewhere and make an alias to `ldoc.lua` on your path. That is, either
an excutable script called 'ldoc' like so:
lua /path/to/ldoc/ldoc.lua $* lua /path/to/ldoc/ldoc.lua $*