From a418859589a5ae5220372f4b9a7d88401ce10afe Mon Sep 17 00:00:00 2001 From: steve donovan Date: Thu, 1 Sep 2011 16:00:16 +0200 Subject: [PATCH] updating documentation --- docs/doc.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/doc.md b/docs/doc.md index 8dc854a..43d2817 100644 --- a/docs/doc.md +++ b/docs/doc.md @@ -539,6 +539,47 @@ Thanks to mitchell's [TextAdept](http://code.google.com/p/textadept/) project, L 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: