Codebase list lua-ldoc / c694526
updating docs steve donovan 12 years ago
1 changed file(s) with 41 addition(s) and 49 deletion(s). Raw diff Collapse all Expand all
+41
-49
docs/doc.md less more
0 ## LDoc - A Lua Documentation Tool
0 ## Introduction
1
2 LDoc is a second-generation documentation tool that can be used as a replacement for LuaDoc. It arose out of my need to document my own projects and only depends on the [Penlight]() libraries.
3
4 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 `module` is deprecated in Lua 5.2.
5
6 Otherwise, the output is very similar, which is no accident since the HTML templates are based directly on LuaDoc. You have an option to ship your own customized templates and style sheets with your project, 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 naturally less can be inferred from the code itself.
7
8 LDoc can provide integrated documentation, with traditional function comments, any readme in Markdown format, and specified source examples. Lua source in examples and the readme will be prettified.
9
10 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.
11
12 ## Commenting Conventions
113
214 LDoc follows the conventions established by Javadoc and later by LuaDoc.
315
1224
1325 You can also use Lua block comments:
1426
15 --[[--
16 Summary. A description
17 ..;
18 ]]
27 --[[--
28 Summary. A description
29 ...;
30 ]]
1931
2032 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.
2133
148160
149161 (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`.
150162
151 ## @see References
163 ## See References
152164
153165 The tag 'see' is used to reference other parts of the documentation, and 'usage' can provide examples of use:
154166
164176
165177 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.
166178
179 References to methods use a colon: `myclass:method`; this is for instance how you would refer to members of a `@type` section.
167180
168181 The example at `tests/complex` shows how @see references are interpreted:
169182
196209 -- @field viscosity
197210 -- @table stdvars
198211
212 `@{ref}` is very useful for referencing your API from code samples and readme text.
199213
200214 ## Sections
201215
202 LDoc supports _explicit_ sections. The need occurs when a module has a lot of functions that need to be put into logical sections.
216 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') you can define a new section ('Macros') to contain these types. There is also a way to declare ad-hoc sections using the `@section` tag.
217
218 The need occurs when a module has a lot of functions that need to be put into logical sections.
203219
204220 --- File functions.
205221 -- Useful utilities for opening foobar format files.
235251 ...
236252
237253 (In an ideal world, we would use the word 'class' instead of 'type', but this would conflict with the LuaDoc usage.)
254
255 A section continues until the next section is found, or end of file.
238256
239257 ## Differences from LuaDoc
240258
271289
272290 LDoc gives the documenter the option to use Markdown to parse the contents of comments.
273291
274
275
276 ## LDoc is Extensible
277
278 LDoc tries to be faithful to LuaDoc, but provides some extensions.
279
280 '@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:
292 ## Adding new Tags
293
294 LDoc tries to be faithful to LuaDoc, but provides some extensions. Aliases for tags can be defined, and new types declared.
281295
282296 --- zero function. Two new ldoc features here; item types
283297 -- can be used directly as tags, and aliases for tags
342356 ...
343357 end
344358
345 ## Supporting Extension modules written in C
359 As always, explicit tags can override this behaviour if it is inappropriate.
360
361 ## Extension modules written in C
346362
347363 LDoc can process C/C++ files:
348364
401417
402418 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.
403419
404 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`:
405
406 ------------
407 -- A new-style module.
408 -- @alias A
409
410 local simple_alias = {}
411 local A = simple_alias
412
413 --- return the answer. And complete the description
414 function A.answer()
415 return 42
416 end
417
418 return simple_alias
419
420 (Here the actual module name is deduced from the file name, just like with `module(...)`)
421
422 It's semi-standard to use 'M' or '_M' for the module alias; LDoc will recognize these automatically.
423
424 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`.
420 `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`.)
425421
426422 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:
427423
440436 $ ldoc --output mylib mylib.lua --> results in docs/mylib.html
441437 $ ldoc --output mylib --dir html mylib.lua --> results in html/mylib.html
442438
443
444439 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.
445440
446 ## Dumping and getting Help about a Module
441 ## Getting Help about a Module
447442
448443 There is an option to simply dump the results of parsing modules. Consider the C example `tests/example/mylib.c':
449444
470465
471466 $ ldoc --filter pl.pretty.dump mylib.c
472467
473 to see a raw dump of the data. (Simply using `dump` here would be a shorthand for `pl.pretty.dump`.)
468 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.
474469
475470 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:
476471
539534
540535 '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'.
541536
542 '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](!).
543
544
545 ## Including source examples and a readme file
537 '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_. ?ref to config.ld for LM
538
539
540 ## Including examples and a readme file
546541
547542 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.
548543
549 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.
544 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.
550545
551546 The line in the `config.ld` that enables this is:
552547
562557
563558 This goes under the 'Topics' global section; the 'Contents' of this document is generated from the second-level (##) headings of the readme.
564559
565 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.
560 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.
566561
567562
568563 ## Fields allowed in `config.ld`
587582 - `examples` a directory or file: can be a table
588583 - `readme` name of readme file (to be processed with Markdown)
589584
590
591585 Available functions are:
592586
593587 - `alias(a,tag)` provide an alias `a` for the tag `tag`, for instance `p` as short for `param`
596590 - `new_type(tag,header,project_level)` used to add new tags, which are put in their own section `header`. They may be 'project level'.
597591
598592
599
600
601593 ## Generating HTML
602594
603 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 '$(...)'.
595 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 '$(...)'.
604596
605597 <h2>Contents</h2>
606598 <ul>