Codebase list lua-ldoc / e150088
Merge tag '1.3.11' fixed 1.3 release Julian Wollrath 11 years ago
10 changed file(s) with 1186 addition(s) and 1148 deletion(s). Raw diff Collapse all Expand all
+7
-7
config.ld less more
0 project='LDoc'
1 title='LDoc documentation'
2 description='A Lua documentation tool'
3 format='discount'
4 file='ldoc.lua'
5 dir='out'
6 readme='docs/doc.md'
0 project='LDoc'
1 title='LDoc documentation'
2 description='A Lua documentation tool'
3 format='discount'
4 file='ldoc.lua'
5 dir='out'
6 readme='doc/doc.md'
+7
-0
doc/config.ld less more
0 project='LDoc'
1 title='LDoc documentation'
2 description='A Lua documentation tool'
3 format='discount'
4 file='../ldoc.lua'
5 dir='../out'
6 readme='doc.md'
+1129
-0
doc/doc.md less more
0 # LDoc, a Lua Documentation Tool
1
2 @lookup doc.md
3
4 ## Introduction
5
6 LDoc is a second-generation documentation tool that can be used as a replacement for
7 [LuaDoc](http://keplerproject.github.com/luadoc/). It arose out of my need to document my
8 own projects and only depends on the [Penlight](https://github.com/stevedonovan/Penlight)
9 libraries.
10
11 It is mostly compatible with LuaDoc, except that certain workarounds are no longer needed.
12 For instance, it is not so married to the idea that Lua modules should be defined using the
13 `module` function; this is not only a matter of taste since this has been deprecated in Lua
14 5.2.
15
16 Otherwise, the output is very similar, which is no accident since the HTML templates are
17 based directly on LuaDoc. You can ship your own customized templates and style sheets with
18 your [own project](http://nilnor.github.com/textui/docs/), however. You have an option to
19 use Markdown to process the documentation, which means no ugly HTML is needed in doc
20 comments. C/C++ extension modules may be documented in a similar way, although function
21 names cannot be inferred from the code itself.
22
23 LDoc can provide integrated documentation, with traditional function comments, any documents
24 in Markdown format, and specified source examples. Lua source in examples and the documents
25 will be prettified.
26
27 Although there are a fair number of command-line options, the preferred route is to write a
28 `config.ld` configuration file in Lua format. By convention, if LDoc is simply invoked as
29 `ldoc .` it will read this file first. In this way, the aim is to make it very easy for
30 end-users to build your documentation using this simple command.
31
32 ## Commenting Conventions
33
34 LDoc follows the conventions established by Javadoc and later by LuaDoc.
35
36 Only 'doc comments' are parsed; these can be started with at least 3 hyphens, or by a empty
37 comment line with at least 3 hypens:
38
39 --- summary.
40 -- Description; this can extend over
41 -- several lines
42
43 -----------------
44 -- This will also do.
45
46 You can also use Lua block comments:
47
48 --[[--
49 Summary. A description
50 ...;
51 ]]
52
53 Any module or script must start with a doc comment; any other files are ignored and a
54 warning issued. The only exception is if the module starts with an explicit `module`
55 statement.
56
57 All doc comments start with a summary sentence, that ends with a period or a question mark.
58 An optional description may follow. Normally the summary sentence will appear in the module
59 contents.
60
61 After this descriptive text, there will typically be _tags_. These follow the convention
62 established by Javadoc and widely used in tools for other languages.
63
64 --- foo explodes text.
65 -- It is a specialized splitting operation on a string.
66 -- @param text the string
67 -- @return a table of substrings
68 function foo (text)
69 ....
70 end
71
72 There are also 'tparam' and 'treturn' which let you [specify a type](#Tag_Modifiers):
73
74 -- @tparam string text the string
75 -- @treturn {string,...} a table of substrings
76
77 There may be multiple 'param' tags, which should document each formal parameter of the
78 function. For Lua, there can also be multiple 'return' tags
79
80 --- solvers for common equations.
81 module("solvers", package.seeall)
82
83 --- solve a quadratic equation.
84 -- @param a first coeff
85 -- @param b second coeff
86 -- @param c third coeff
87 -- @return first root, or nil
88 -- @return second root, or imaginary root error
89 function solve (a,b,c)
90 local disc = b^2 - 4*a*c
91 if disc < 0 then
92 return nil,"imaginary roots"
93 else
94 disc = math.sqrt(disc)
95 return (-b + disc)/2*a,
96 (-b - disc)/2*a
97 end
98 end
99
100 ...
101
102 This is the common module style used in Lua 5.1, but it's increasingly common to see less
103 'magic' ways of creating modules in Lua. Since `module` is deprecated in Lua 5.2, any
104 future-proof documentation tool needs to handle these styles gracefully:
105
106 --- a test module
107 -- @module test
108
109 local test = {}
110
111 --- first test.
112 function test.one()
113 ...
114 end
115
116 ...
117
118 return test
119
120 Here the name of the module is explicitly given using the 'module' tag. If you leave this
121 out, then LDoc will infer the name of the module from the name of the file and its relative
122 location in the filesystem; this logic is also used for the `module(...)` idiom. (How this
123 works and when you need to provide extra information is discussed later.)
124
125 It is common to use a local name for a module when declaring its contents. In this case the
126 'alias' tag can tell LDoc that these functions do belong to the module:
127
128 --- another test.
129 -- @module test2
130 -- @alias M
131
132 local M = {}
133
134 -- first test.
135 function M.one()
136 ..
137 end
138
139 return M
140
141 `M` and `_M` are used commonly enough that LDoc will recognize them as aliases
142 automatically, but 'alias' allows you to use any identifier.
143
144 LDoc tries to deduce the function name and the formal parameter names from examining the
145 code after the doc comment. It also recognizes the 'unsugared' way of defining functions as
146 explicit assignment to a variable:
147
148 --- second test.
149 M.two = function(...) ... end
150
151 Apart from exported functions, a module usually contains local functions. By default, LDoc
152 does not include these in the documentation, but they can be enabled using the `--all` flag.
153 They can be documented just like 'public' functions:
154
155 --- it's clear that boo is local from context.
156 local function boo(...) .. end
157
158 local foo
159
160 --- we need to give a hint here for foo
161 -- @local here
162 function foo(...) .. end
163
164 Modules can of course export tables and other values. The classic way to document a table
165 looks like this:
166
167 --- a useful table of constants
168 -- @field alpha first correction
169 -- @field beta second correction
170 -- @field gamma fudge factor
171 -- @table constants
172
173 Here the kind of item is made explicit by the 'table' tag; tables have 'fields' in the same
174 way as functions have parameters.
175
176 This can get tedious, so LDoc will attempt to extract table documentation from code:
177
178 --- a useful table of constants
179 M.constants = {
180 alpha = 0.23, -- first correction
181 beta = 0.443, -- second correction
182 gamma = 0.01 -- fudge factor
183 }
184
185 The rule followed here is `NAME = <table-constructor>`. If LDoc can't work out the name and
186 type from the following code, then a warning will be issued, pointing to the file and
187 location.
188
189 Another kind of module-level type is 'field', such as follows:
190
191 --- module version.
192 M._VERSION = '0.5'
193
194 That is, a module may contain exported functions, local functions, tables and fields.
195
196 When the code analysis would lead to the wrong type, you can always be explicit.
197
198 --- module contents.
199 -- @field _CONTENTS
200 M._CONTENTS = {constants=true,one=true,...}
201
202 The order of tags is not important, but as always, consistency is useful. Tags like 'param'
203 and 'return' can be specified multiple times, whereas a type tag like 'function' can only
204 occur once in a comment. The basic rule is that a single doc comment can only document one
205 entity.
206
207 By default, LDoc will process any file ending in '.lua' or '.luadoc' in a specified
208 directory; you may point it to a single file as well. A 'project' usually consists of many
209 modules in one or more _packages_. The generated `index.html` will point to the generated
210 documentation for each of these modules.
211
212 If only one module or script is documented for a project, then the `index.html` generated
213 contains the documentation for that module, since an index pointing to one module would be
214 redundant.
215
216 (If you want to document a script, there is a project-level type 'script' for that.)
217
218 ## See References
219
220 The tag 'see' is used to reference other parts of the documentation, and 'usage' can provide
221 examples of use:
222
223 ---------
224 -- split a string in two.
225 -- @param s the string
226 -- @param delim the delimiter (default space)
227 -- @return first part
228 -- @return second part
229 -- @usage local hello,world = split2("hello world")
230 -- @see split
231 funtion split2(s,delim) .. end
232
233 Here it's assumed that 'split' is a function defined in the same module. If you wish to link
234 to a function in another module, then the reference has to be qualified.
235
236 References to methods use a colon: `myclass:method`; this is for instance how you would
237 refer to members of a `@type` section.
238
239 The example at `tests/complex` shows how @see references are interpreted:
240
241 complex.util.parse
242 complex.convert.basic
243 complex.util
244 complex.display
245 complex
246
247 You may of course use the full name of a module or function, but can omit the top-level
248 namespace - e.g. can refer to the module `util` and the function `display.display_that`
249 directly. Within a module, you can directly use a function name, e.g. in `display` you can
250 say `display_this`.
251
252 What applies to functions also applies to any module-level item like tables. New
253 module-level items can be defined and they will work according to these rules.
254
255 If a reference is not found within the project, LDoc checks to see if it is a reference to a
256 Lua standard function or table, and links to the online Lua manual. So references like
257 'table.concat' are handled sensibly.
258
259 References may be made inline using the @\{ref} syntax. This may appear anywhere in the
260 text, and is more flexible than @see. In particular, it provides one way to document the
261 type of a parameter or return value when that type has a particular structure:
262
263 ------
264 -- extract standard variables.
265 -- @param s the string
266 -- @return @\{stdvars}
267 function extract_std(s) ... end
268
269 ------
270 -- standard variables.
271 -- Use @\{extract_std} to parse a string containing variables,
272 -- and @\{pack_std} to make such a string.
273 -- @field length
274 -- @field duration
275 -- @field viscosity
276 -- @table stdvars
277
278 @\{ref} is very useful for referencing your API from code samples and readme text. (I've had
279 to throw in a spurious backspace to stop expansion in this example.)
280
281 The link text can be changed from the default by the extended syntax @\{ref|text}.
282
283 You can also put references in backticks, like `\`stdvars\``. This is commonly used in
284 Markdown to indicate code, so it comes naturally when writing documents. It is controlled by
285 the configuration variable `backtick_references`; the default is `true` if you use Markdown
286 in your project, but can be specified explicitly in your `config.ld`.
287
288 ### Custom @see References
289
290 It's useful to define how to handle references external to a project. For instance, in the
291 [luaposix](https://github.com/luaposix/luaposix) project we wanted to have `man` references
292 to the corresponding C function:
293
294 ------------
295 -- raise a signal on this process.
296 -- @see raise(3)
297 -- @int nsig
298 -- @return integer error cod
299 function raise (nsig)
300 end
301
302 These see references always have this particular form, and the task is to turn them into
303 online references to the Linux manpages. So in `config.ld` we have:
304
305 local upat = "http://www.kernel.org/doc/man-pages/online/pages/man%s/%s.%s.html"
306
307 custom_see_handler('^(%a+)%((%d)%)$',function(name,section)
308 local url = upat:format(section,name,section)
309 local name = name .. '(' ..section..')'
310 return name, url
311 end)
312
313 '^(%a+)%((%d)%)$' both matches the pattern and extracts the name and its section. THen it's
314 a simple matter of building up the appropriate URL. The function is expected to
315 return _link text_ and _link source_ and the patterns are checked before LDoc tries to resolve
316 project references. So it is best to make them match as exactly as possible.
317
318 ## Sections
319
320 LDoc supports _explicit_ sections. By default, the sections correspond to the pre-existing
321 types in a module: 'Functions', 'Tables' and 'Fields' (There is another default section
322 'Local Functions' which only appears if LDoc is invoked with the `--all` flag.) But new
323 sections can be added; the first mechanism is when you define a new type (say 'macro') a new
324 section ('Macros') is created to contain these types. There is also a way to declare ad-hoc
325 sections using the `@section` tag.
326
327 The need occurs when a module has a lot of functions that need to be put into logical
328 sections.
329
330 --- File functions.
331 -- Useful utilities for opening foobar format files.
332 -- @section file
333
334 --- open a file
335 ...
336
337 --- read a file
338 ...
339
340 --- Encoding operations.
341 -- Encoding foobar output in different ways.
342 -- @section encoding
343
344 ...
345
346 A section doc-comment has the same structure as a normal doc-comment; the summary is used as
347 the new section title, and the description will be output at the start of the function
348 details for that section.
349
350 In any case, sections appear under 'Contents' on the left-hand side. See the
351 [winapi](http://stevedonovan.github.com/winapi/api.html) documentation for an example of how
352 this looks.
353
354 Arguably a module writer should not write such very long modules, but it is not the job of
355 the documentation tool to limit the programmer!
356
357 A specialized kind of section is `type`: it is used for documenting classes. The functions
358 (or fields) within a type section are considered to be the methods of that class.
359
360 --- A File class.
361 -- @type File
362
363 ....
364 --- get the modification time.
365 -- @return standard time since epoch
366 function File:mtime()
367 ...
368 end
369
370 (In an ideal world, we would use the word 'class' instead of 'type', but this would conflict
371 with the LuaDoc usage.)
372
373 A section continues until the next section is found, `@section end`, or end of file.
374
375 You can put items into an implicit section using the @within tag. This allows you to put
376 adjacent functions in different sections, so that you are not forced to order your code
377 in a particular way.
378
379 Sometimes a module may logically span several files. There will be a master module with name
380 'foo' and other files which when required add functions to that module. If these files have
381 a @submodule tag, their contents will be placed in the master module documentation. However,
382 a current limitation is that the master module must be processed before the submodules.
383
384 See the `tests/submodule` example for how this works in practice.
385
386 ## Differences from LuaDoc
387
388 LDoc only does 'module' documentation, so the idea of 'files' is redundant.
389
390 One added convenience is that it is easier to name entities:
391
392 ------------
393 -- a simple module.
394 -- (LuaDoc)
395 -- @class module
396 -- @name simple
397
398 ------------
399 -- a simple module.
400 -- (LDoc)
401 -- @module simple
402
403 This is because type names (like 'function', 'module', 'table', etc) can function as tags.
404 LDoc also provides a means to add new types (e.g. 'macro') using a configuration file which
405 can be shipped with the source. If you become bored with typing 'param' repeatedly then you
406 can define an alias for it, such as 'p'. This can also be specified in the configuration file.
407
408 LDoc will also work with C/C++ files, since extension writers clearly have the same
409 documentation needs as Lua module writers.
410
411 LDoc allows you to attach a _type_ to a parameter or return value
412
413 --- better mangler.
414 -- @tparam string name
415 -- @int max length
416 -- @treturn string mangled name
417 function strmangler(name,max)
418 ...
419 end
420
421 `int` here is short for `tparam int` (see @{Tag_Modifiers})
422
423 It's common for types to be optional, or have different types, so the type can be like
424 '?int|string' which renders as '(int or string)', or '?int', which renders as
425 '(optional int)'.
426
427 LDoc gives the documenter the option to use Markdown to parse the contents of comments.
428
429 Since 1.3, LDoc allows the use of _colons_ instead of @.
430
431 --- a simple function.
432 -- string name person's name
433 -- int: age age of person
434 -- !person: person object
435 -- treturn: ?string
436 -- function check(name,age)
437
438 However, you must either use the `--colon` flag or set `colon=true` in your `config.ld`.
439
440 In this style, types may be used directly if prefixed with '!' or '?' (for type-or-nil)
441
442 (see `tests/styles/colon.lua`)
443
444 ## Adding new Tags
445
446 LDoc tries to be faithful to LuaDoc, but provides some extensions. Aliases for tags can be
447 defined, and new types declared.
448
449 --- zero function. Two new ldoc features here; item types
450 -- can be used directly as tags, and aliases for tags
451 -- can be defined in config.ld.
452 -- @function zero_fun
453 -- @p k1 first
454 -- @p k2 second
455
456 Here an alias for 'param' has been defined. If a file `config.ld` is found in the source,
457 then it will be loaded as Lua data. For example, the configuration for the above module
458 provides a title and defines an alias for 'param':
459
460 title = "testmod docs"
461 project = "testmod"
462 alias("p","param")
463
464 Extra tag _types_ can be defined:
465
466 new_type("macro","Macros")
467
468 And then used as any other type:
469
470 -----
471 -- A useful macro. This is an example of a custom type.
472 -- @macro first_macro
473 -- @see second_function
474
475 This will also create a new module section called 'Macros'.
476
477 If your new type has arguments or fields, then specify the name:
478
479 new_type("macro","Macros",false,"param")
480
481 (The third argument means that this is not a _project level_ tag)
482
483 Then you may say:
484
485 -----
486 -- A macro with arguments.
487 -- @macro second_macro
488 -- @param x the argument
489
490 And the arguments will be displayed under the subsection 'param'
491
492
493 ## Inferring more from Code
494
495 The qualified name of a function will be inferred from any `function` keyword following the
496 doc comment. LDoc goes further with this kind of code analysis, however.
497
498 Instead of:
499
500 --- first table.
501 -- @table one
502 -- @field A alpha
503 -- @field B beta
504 M.one = {
505 A = 1,
506 B = 2;
507 }
508
509 you can write:
510
511 --- first table
512 -- @table one
513 M.one = {
514 A = 1, -- alpha
515 B = 2; -- beta
516 }
517
518 Simularly, function parameter comments can be directly used:
519
520 ------------
521 -- third function. Can also provide parameter comments inline,
522 -- provided they follow this pattern.
523 function mod1.third_function(
524 alpha, -- correction A
525 beta, -- correction B
526 gamma -- factor C
527 )
528 ...
529 end
530
531 As always, explicit tags can override this behaviour if it is inappropriate.
532
533 ## Extension modules written in C
534
535 LDoc can process C/C++ files:
536
537 @plain
538 /***
539 Create a table with given array and hash slots.
540 @function createtable
541 @param narr initial array slots, default 0
542 @param nrec initial hash slots, default 0
543 @return the new table
544 */
545 static int l_createtable (lua_State *L) {
546 ....
547
548 Both `/**` and `///` are recognized as starting a comment block. Otherwise, the tags are
549 processed in exactly the same way. It is necessary to specify that this is a function with a
550 given name, since this cannot be reliably be inferred from code. Such a file will need a
551 module comment, which is treated exactly as in Lua.
552
553 An unknown extension can be associated with a language using a call like
554 `add_language_extension('lc','c')` in `config.ld`. (Currently the language can only be 'c'
555 or 'lua'.)
556
557 An LDoc feature which is particularly useful for C extensions is _module merging_. If several
558 files are all marked as `@module lib` then a single module `lib` is generated, containing all
559 the docs from the separate files.
560
561 See 'tests/examples/mylib.c' for the full example.
562
563 ## Basic Usage
564
565 For example, to process all files in the 'lua' directory:
566
567 $ ldoc lua
568 output written to docs/
569
570 Thereafter the `docs` directory will contain `index.html` which points to individual modules
571 in the `modules` subdirectory. The `--dir` flag can specify where the output is generated,
572 and will ensure that the directory exists. The output structure is like LuaDoc: there is an
573 `index.html` and the individual modules are in the `modules` subdirectory. This applies to
574 all project-level types, so that you can also get `scripts`, `examples` and `topics`
575 directories.
576
577 If your modules use `module(...)` then the module name has to be deduced. If `ldoc` is run
578 from the root of the package, then this deduction does not need any help - e.g. if your
579 package was `foo` then `ldoc foo` will work as expected. If we were actually in the `foo`
580 directory then `ldoc -b .. .` will correctly deduce the module names. An example would be
581 generating documentation for LuaDoc itself:
582
583 $ ldoc -b .. /path/to/luadoc
584
585 Without the `-b` setting the base of the package to the _parent_ of the directory, implicit
586 modules like `luadoc.config` will be incorrectly placed in the global namespace.
587
588 For new-style modules, that don't use `module()`, it is recommended that the module comment
589 has an explicit `@module PACKAGE.NAME`. If it does not, then `ldoc` will still attempt to
590 deduce the module name, but may need help with `--package/-b` as above.
591
592 `format = 'markdown'` can be used in your `config.ld` and will be used to process summaries
593 and descriptions. This requires [markdown.lua](http://www.frykholm.se/files/markdown.lua) by
594 Niklas Frykholm to be installed (this can be most easily done with `luarocks install
595 markdown`.) A much faster alternative is
596 [lua-discount](http://asbradbury.org/projects/lua-discount/) which you can use by setting
597 `format` to 'discount' after installing using `luarocks install lua-discount`) The
598 [discount](http://www.pell.portland.or.us/~orc/Code/discount/) Markdown processor
599 additionally has more features than the pure Lua version, such as PHP-Extra style tables.
600 As a special case, LDoc will fall back to using `markdown.lua` if it cannot find `discount`.
601
602 `format = 'markdown'` can be used in your `config.ld` and will be used to process summaries
603 and descriptions. This requires a markdown processor.
604 LDoc knows how to use:
605
606 - [markdown.lua](http://www.frykholm.se/files/markdown.lua) a pure Lua processor by
607 Niklas Frykholm (this can be installed easily with `luarocks install markdown`.)
608 - [lua-discount](http://asbradbury.org/projects/lua-discount/), a faster alternative
609 (installed with `luarocks install lua-discount`). lua-discount uses the C
610 [discount](http://www.pell.portland.or.us/~orc/Code/discount/) Markdown processor which has
611 more features than the pure Lua version, such as PHP-Extra style tables.
612 - [lunamark](http://jgm.github.com/lunamark/), another pure Lua processor, faster than
613 markdown, and with extra features (`luarocks install lunamark`).
614
615 You can request the processor you like with `format = 'markdown|discount|lunamark'`, and
616 LDoc will attempt to use it. If it can't find it, it will look for one of the other
617 markdown processors. If it can't find any markdown processer, it will fall back to text
618 processing.
619
620
621 A special case is if you simply say 'ldoc .'. Then there _must_ be a `config.ld` file
622 available in the directory, and it can specify the file:
623
624 file = "mymod.lua"
625 title = "mymod documentation"
626 description = "mymod does some simple but useful things"
627
628 `file` can of course point to a directory, just as with the `--file` option. This mode makes
629 it particularly easy for the user to build the documentation, by allowing you to specify
630 everything explicitly in the configuration.
631
632 In `config.ld`, `file` may be a Lua table, containing file names or directories; if it has
633 an `exclude` field then that will be used to exclude files from the list, for example
634 `{'examples', exclude = {'examples/slow.lua'}}`.
635
636
637 ## Processing Single Modules
638
639 `--output` can be used to give the output file a different name. This is useful for the
640 special case when a single module file is specified. Here an index would be redundant, so
641 the single HTML file generated contains the module documentation.
642
643 $ ldoc mylib.lua --> results in docs/index.html
644 $ ldoc --output mylib mylib.lua --> results in docs/mylib.html
645 $ ldoc --output mylib --dir html mylib.lua --> results in html/mylib.html
646
647 The default sections used by LDoc are 'Functions', 'Tables' and 'Fields', corresponding to
648 the built-in types 'function', 'table' and 'field'. If `config.ld` contains something like
649 `new_type("macro","Macros")` then this adds a new section 'Macros' which contains items of
650 'macro' type - 'macro' is registered as a new valid tag name. The default template then
651 presents items under their corresponding section titles, in order of definition.
652
653 ## Getting Help about a Module
654
655 There is an option to simply dump the results of parsing modules. Consider the C example
656 `tests/example/mylib.c':
657
658 @plain
659 $ ldoc --dump mylib.c
660 ----
661 module: mylib A sample C extension.
662 Demonstrates using ldoc's C/C++ support. Can either use /// or /*** */ etc.
663
664 function createtable(narr, nrec)
665 Create a table with given array and hash slots.
666 narr initial array slots, default 0
667 nrec initial hash slots, default 0
668
669 function solve(a, b, c)
670 Solve a quadratic equation.
671 a coefficient of x^2
672 b coefficient of x
673 c constant
674 return {"first root","second root"}
675
676 This is useful to quickly check for problems; here we see that `createable` did not have a
677 return tag.
678
679 LDoc takes this idea of data dumping one step further. If used with the `-m` flag it will
680 look up an installed Lua module and parse it. If it has been marked up in LuaDoc-style then
681 you will get a handy summary of the contents:
682
683 @plain
684 $ ldoc -m pl.pretty
685 ----
686 module: pl.pretty Pretty-printing Lua tables.
687 * read(s) - read a string representation of a Lua table.
688 * write(tbl, space, not_clever) - Create a string representation of a Lua table.
689
690 * dump(t, ...) - Dump a Lua table out to a file or stdout.
691
692 You can specify a fully qualified function to get more information:
693
694 @plain
695 $ ldoc -m pl.pretty.write
696
697 function write(tbl, space, not_clever)
698 create a string representation of a Lua table.
699 tbl {table} Table to serialize to a string.
700 space {string} (optional) The indent to use.
701 Defaults to two spaces.
702 not_clever {bool} (optional) Use for plain output, e.g {['key']=1}.
703 Defaults to false.
704
705 LDoc knows about the basic Lua libraries, so that it can be used as a handy console reference:
706
707 @plain
708 $> ldoc -m assert
709
710 function assert(v, message)
711 Issues an error when the value of its argument `v` is false (i.e.,
712 nil or false); otherwise, returns all its arguments.
713 `message` is an error
714 message; when absent, it defaults to "assertion failed!"
715 v
716 message
717
718 Thanks to Mitchell's [Textadept](http://foicica.com/textadept/) project, LDoc has a
719 set of `.luadoc` files for all the standard tables, plus
720 [LuaFileSystem](http://keplerproject.github.com/luafilesystem/) and
721 [LPeg](http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html).
722
723 @plain
724 $> ldoc -m lfs.lock
725
726 function lock(filehandle, mode, start, length)
727 Locks a file or a part of it.
728 This function works on open files; the file
729 handle should be specified as the first argument. The string mode could be
730 either r (for a read/shared lock) or w (for a write/exclusive lock). The
731 optional arguments start and length can be used to specify a starting point
732 and its length; both should be numbers.
733 Returns true if the operation was successful; in case of error, it returns
734 nil plus an error string.
735 filehandle
736 mode
737 start
738 length
739
740 ## Anatomy of a LDoc-generated Page
741
742 [winapi](http://stevedonovan.github.com/winapi/api.html) can be used as a good example of a
743 module that uses extended LDoc features.
744
745 The _navigation section_ down the left has several parts:
746
747 - The project name ('project' in the config)
748 - A project description ('description')
749 - ''Contents'' of the current page
750 - ''Modules'' listing all the modules in this project
751
752 Note that `description` will be passed through Markdown, if it has been specified for the
753 project. This gives you an opportunity to make lists of links, etc; any '##' headers will be
754 formatted like the other top-level items on the navigation bar.
755
756 'Contents' is automatically generated. It will contain any explicit sections, if they have
757 been used. Otherwise you will get the usual categories: 'Functions', 'Tables' and 'Fields'.
758
759 'Modules' will appear for any project providing Lua libraries; there may also be a 'Scripts'
760 section if the project contains Lua scripts. For example,
761 [LuaMacro](http://stevedonovan.github.com/LuaMacro/docs/api.html) has a driver script `luam`
762 in this section. The
763 [builtin](http://stevedonovan.github.com/LuaMacro/docs/modules/macro.builtin.html) module
764 only defines macros, which are defined as a _custom tag type_.
765
766 The _content section_ on the right shows:
767
768 - The module summary and description
769 - The contents summary, per section as above
770 - The detailed documentation for each item
771
772 As before, the description can use Markdown. The summary contains the contents of each
773 section as a table, with links to the details. This is where the difference between an
774 item's summary and an item's description is important; the first will appear in the contents
775 summary. The item details show the item name and its summary again, followed by the
776 description. There are then sections for the following tags: 'param', 'usage', 'return' and
777 'see' in that order. (For tables, 'Fields' is used instead of 'Parameters' but internally
778 fields of a table are stored as the 'param' tag.)
779
780 You can of course customize the default template, but there are some parameters that can
781 control what the template will generate. Setting `one` to `true` in your configuration file
782 will give a _one-column_ layout, which can be easier to use as a programming reference. You
783 can suppress the contents summary with `no_summary`.
784
785 ## Customizing the Page
786
787 Setting `no_return_or_parms` to `true` will suppress the display of 'param' and 'return'
788 tags. This may appeal to programmers who dislike the traditional @tag soup xDoc style and
789 prefer to comment functions just with a description. This is particularly useful when using
790 Markdown in a stylized way to specify arguments:
791
792 ---------
793 -- This extracts the shortest common substring from the strings _s1_ and _s2_
794 function M.common_substring(s1,s2)
795
796 Here I've chosen to italicise parameter names; the main thing is to be consistent.
797
798 This style is close to the Python [documentation
799 standard](http://docs.python.org/library/array.html#module-array), especially when used with
800 `no_summary`.
801
802 It is also very much how the Lua documentation is ordered. For instance, this configuration
803 file formats the built-in documentation for the Lua global functions in a way which is close
804 to the original:
805
806 project = 'Lua'
807 description = 'Lua Standard Libraries'
808 file = {'ldoc/builtin',exclude = {'ldoc/builtin/globals.lua'}}
809 no_summary = true
810 no_return_or_parms = true
811 format = 'discount'
812
813
814 Generally, using Markdown gives you the opportunity to structure your documentation in any
815 way you want; particularly if using lua-discount and its [table
816 syntax](http://michelf.com/projects/php-markdown/extra/#table); the desired result can often
817 be achieved then by using a custom style sheet.
818
819 ## Examples
820
821 It has been long known that documentation generated just from the source is not really
822 adequate to explain _how_ to use a library. People like reading narrative documentation,
823 and they like looking at examples. Previously I found myself dealing with source-generated
824 and writer-generated documentation using different tools, and having to match these up.
825
826 LDoc allows for source examples to be included in the documentation. For example, see the
827 online documentation for [winapi](http://stevedonovan.github.com/winapi/api.html). The
828 function `utf8_expand` has a `@see` reference to 'testu.lua' and following that link gives
829 you a pretty-printed version of the code.
830
831 The line in the `config.ld` that enables this is:
832
833 examples = {'examples', exclude = {'examples/slow.lua'}}
834
835 That is, all files in the `examples` folder are to be pretty-printed, except for `slow.lua`
836 which is meant to be called from one of the examples. The see-reference to `testu.lua`
837 resolves to 'examples/testu.lua.html'.
838
839 Examples may link back to the API documentation, for instance the example `input.lua` has a
840 @\{spawn_process} inline reference.
841
842 ## Readme files
843
844 Like all good Github projects, Winapi has a `readme.md`:
845
846 readme = "readme.md"
847
848 This goes under the 'Topics' global section; the 'Contents' of this document is generated
849 from the second-level (##) headings of the readme.
850
851 Readme files are always processed with the current Markdown processor, but may also contain @\{} references back
852 to the documentation and to example files. Any symbols within backticks will be expanded as
853 references, if possible. As with doc comments, a link to a standard Lua function like
854 @\{os.execute} will work as well. Any code sections will be pretty-printed as Lua, unless
855 the first indented line is '@plain'. (See the source for this readme to see how it's used.)
856
857 Another name for `readme` is `topics`, which is more descriptive. From LDoc 1.2,
858 `readme/topics` can be a list of documents. These act as a top-level table-of-contents for
859 your documentation. Currently, if you want them in a particular order, then use names like
860 `01-introduction.md` etc which sort appropriately.
861
862 The first line of a document may be a Markdown `#` title. If so, then LDoc will regard the
863 next level as the subheadings, normally second-level `##`. But if the title is already
864 second-level, then third-level headings will be used `###`, and so forth. The implication is
865 that the first heading must be top-level relative to the headings that follow, and must
866 start at the first line.
867
868 A reference like @\{string.upper} is unambiguous, and will refer to the online Lua manual.
869 In a project like Penlight, it can get tedious to have to write out fully qualified names
870 like @\{pl.utils.printf}. The first simplification is to use the `package` field to resolve
871 unknown references, which in this case is 'pl'. (Previously we discussed how `package` is
872 used to tell LDoc where the base package is in cases where the module author wishes to
873 remain vague, but it does double-duty here.) A further level of simplification comes from
874 the @lookup directive in documents, which must start at the first column on its own line.
875 For instance, if I am talking about `pl.utils`, then I can say "@lookup utils" and
876 thereafter references like @\{printf} will resolve correctly.
877
878 If you look at the source for this document, you will see a `@lookup doc.md` which allows
879 direct references to sections like @{Readme_files|this}.
880
881 Remember that the default is for references in backticks to be resolved; unlike @
882 references, it is not an error if the reference cannot be found.
883
884 The _sections_ of a document (the second-level headings) are also references. This
885 particular section can be refered to as @\{doc.md.Resolving_References_in_Documents} - the
886 rule is that any non-alphabetic character is replaced by an underscore.
887
888
889 ## Tag Modifiers
890
891 Ay tag may have _tag modifiers_. For instance, you may say
892 @\param[type=number] and this associates the modifier `type` with value `number` with this
893 particular param tag. A shorthand can be introduced for this common case, which is "@tparam
894 <type> <parmname> <comment>"; in the same way @\treturn is defined.
895
896 This is useful for larger projects where you want to provide the argument and return value
897 types for your API, in a structured way that can be easily extracted later. There is a
898 useful function for creating new tags that can be used in `config.ld`:
899
900 tparam_alias('string','string')
901
902 That is, "@string" will now have the same meaning as "@tparam string".
903
904 From 1.3, the following standard type aliases are predefined:
905
906 * `string`
907 * `number`
908 * `int`
909 * `bool` Lua 'boolean' type
910 * `func` 'function' (using 'function' would conflict with the type)
911 * `tab` 'table'
912 * `thread`
913
914 The exact form of `<type>` is not defined, but here is a suggested scheme:
915
916 number -- a plain type
917 Bonzo -- a known type; a reference link will be generated
918 {string,number} -- a 'list' tuple, built from type expressions
919 {A=string,N=number} -- a 'struct' tuple, ditto
920 {Bonzo,...} -- an array of Bonzo objects
921 {[string]=Bonzo,...} -- a map of Bonzo objects with string keys
922 Array(Bonzo) -- (assuming that Array is a container)
923
924 Currently the `type` modifier is the only one known and used by LDoc when generating HTML
925 output. However, any other modifiers are allowed and are available for use with your own
926 templates or for extraction by your own tools.
927
928 The `alias` function within configuration files has been extended so that alias tags can be
929 defined as a tag plus a set of modifiers. So `tparam` is defined as:
930
931 alias('tparam',{'param',modifiers={type="$1"}})
932
933 As an extension, you're allowed to use '@param' tags in table definitions. This makes it
934 possible to use type alias like '@string' to describe fields, since they will expand to
935 'param'.
936
937 Another modifier understood by LDoc is `opt`. For instance,
938
939 ---- testing [opt]
940 -- @param one
941 -- @param[opt] two
942 -- @param three
943 -- @param[opt] four
944 function two (one,two,three,four)
945 end
946 ----> displayed as: two (one [, two], three [, four])
947
948 This modifier can also be used with type aliases. If a value is given for the modifier
949 then LDoc can present this as the default value for this optional argument.
950
951 --- a function with typed args.
952 -- If the Lua function has varargs, then
953 -- you may document an indefinite number of extra arguments!
954 -- @string name person's name
955 -- @int age
956 -- @string[opt='gregorian'] calender optional calendar
957 -- @int[opt=0] offset optional offset
958 -- @treturn string
959 function one (name,age,...)
960 end
961 ----> displayed as: one (name, age [, calender='gregorian' [, offset=0]])
962
963 (See `tests/styles/four.lua`)
964
965 ## Fields allowed in `config.ld`
966
967 These mostly have the same meaning as the corresponding parameters:
968
969 - `file` a file or directory containing sources. In `config.ld` this can also be a table
970 of files and directories.
971 - `project` name of project, used as title in top left
972 - `title` page title, default 'Reference'
973 - `package ` explicit base package name; also used for resolving references in documents
974 - `all` show local functions, etc as well in the docs
975 - `format` markup processor, can be 'plain' (default), 'markdown' or 'discount'
976 - `output` output name (default 'index')
977 - `dir` directory for output files (default 'docs')
978 - `ext` extension for output (default 'html')
979 - `one` use a one-column layout
980 - `style`, `template`: together these specify the directories for the style and and the
981 template. In `config.ld` they may also be `true`, meaning use the same directory as the
982 configuration file.
983
984 These only appear in `config.ld`:
985
986 - `description` a project description used under the project title
987 - `examples` a directory or file: can be a table
988 - `readme` name of readme file (to be processed with Markdown)
989 - `no_return_or_parms` don't show parameters or return values in output
990 - `backtick_references` whether references in backticks will be resolved
991 - `manual_url` point to an alternative or local location for the Lua manual, e.g.
992 'file:///D:/dev/lua/projects/lua-5.1.4/doc/manual.html'
993 - `one` use a one-column output format
994 - `no_summary` suppress the Contents summary
995
996 Available functions are:
997
998 - `alias(a,tag)` provide an alias `a` for the tag `tag`, for instance `p` as short for
999 `param`
1000 - `add_language_extension(ext,lang)` here `lang` may be either 'c' or 'lua', and `ext` is
1001 an extension to be recognized as this language
1002 - `add_section`
1003 - `new_type(tag,header,project_level)` used to add new tags, which are put in their own
1004 section `header`. They may be 'project level'.
1005 - `tparam_alias(name,type)` for instance, you may wish that `Object` means `@\tparam
1006 Object`.
1007 - `custom_see_handler(pattern,handler)`. If a reference matches `pattern`, then the
1008 extracted values will be passed to `handler`. It is expected to return link text
1009 and a suitable URI. (This match will happen before default processing.)
1010
1011 ## Annotations and Searching for Tags
1012
1013 Annotations are special tags that can be used to keep track of internal development status.
1014 The known annotations are 'todo', 'fixme' and 'warning'. They may occur in regular
1015 function/table doc comments, or on their own anywhere in the code.
1016
1017 --- Testing annotations
1018 -- @module annot1
1019 ...
1020 --- first function.
1021 -- @todo check if this works!
1022 function annot1.first ()
1023 if boo then
1024
1025 end
1026 --- @fixme what about else?
1027 end
1028
1029 Although not currently rendered by the template as HTML, they can be extracted by the
1030 `--tags` command, which is given a comma-separated list of tags to list.
1031
1032 @plain
1033 D:\dev\lua\LDoc\tests> ldoc --tags todo,fixme annot1.lua
1034 d:\dev\lua\ldoc\tests\annot1.lua:14: first: todo check if this works!
1035 d:\dev\lua\ldoc\tests\annot1.lua:19: first-fixme1: fixme what about else?
1036
1037
1038 ## Generating HTML
1039
1040 LDoc, like LuaDoc, generates output HTML using a template, in this case `ldoc_ltp.lua`. This
1041 is expanded by the powerful but simple preprocessor devised originally by [Rici
1042 Lake](http://lua-users.org/wiki/SlightlyLessSimpleLuaPreprocessor) which is now part of
1043 Penlight. There are two rules - any line starting with '#' is Lua code, which can also be
1044 embedded with '$(...)'.
1045
1046 <h2>Contents</h2>
1047 <ul>
1048 # for kind,items in module.kinds() do
1049 <li><a href="#$(no_spaces(kind))">$(kind)</a></li>
1050 # end
1051 </ul>
1052
1053 This is then styled with `ldoc.css`. Currently the template and stylesheet is very much
1054 based on LuaDoc, so the results are mostly equivalent; the main change that the template has
1055 been more generalized. The default location (indicated by '!') is the directory of `ldoc.lua`.
1056
1057 You may customize how you generate your documentation by specifying an alternative style
1058 sheet and/or template, which can be deployed with your project. The parameters are `--style`
1059 and `--template`, which give the directories where `ldoc.css` and `ldoc.ltp` are to be
1060 found. If `config.ld` contains these variables, they are interpreted slightly differently;
1061 if they are true, then it means 'use the same directory as config.ld'; otherwise they must
1062 be a valid directory relative to the ldoc invocation.
1063
1064 An example of fully customized documentation is `tests/example/style`: this is what you
1065 could call 'minimal Markdown style' where there is no attempt to tag things (except
1066 emphasizing parameter names). The narrative alone _can_ to be sufficient, if it is written
1067 appropriately.
1068
1069 Of course, there's no reason why LDoc must always generate HTML. `--ext` defines what output
1070 extension to use; this can also be set in the configuration file. So it's possible to write
1071 a template that converts LDoc output to LaTex, for instance. The separation of processing
1072 and presentation makes this kind of new application possible with LDoc.
1073
1074 ## Internal Data Representation
1075
1076 The `--dump` flag gives a rough text output on the console. But there is a more
1077 customizeable way to process the output data generated by LDoc, using the `--filter`
1078 parameter. This is understood to be a fully qualified function (module + name). For example,
1079 try
1080
1081 $ ldoc --filter pl.pretty.dump mylib.c
1082
1083 to see a raw dump of the data. (Simply using `dump` as the value here would be a shorthand
1084 for `pl.pretty.dump`.) This is potentially very powerful, since you may write arbitrary Lua
1085 code to extract the information you need from your project.
1086
1087 For instance, a file `custom.lua` like this:
1088
1089 return {
1090 filter = function (t)
1091 for _, mod in ipairs(t) do
1092 print(mod.type,mod.name,mod.summary)
1093 end
1094 end
1095 }
1096
1097 Can be used like so:
1098
1099 ~/LDoc/tests/example$ ldoc --filter custom.filter mylib.c
1100 module mylib A sample C extension.
1101
1102 The basic data structure is straightforward: it is an array of 'modules' (project-level
1103 entities, including scripts) which each contain an `item` array (functions, tables and so
1104 forth).
1105
1106 For instance, to find all functions which don't have a @return tag:
1107
1108 return {
1109 filter = function (t)
1110 for _, mod in ipairs(t) do
1111 for _, item in ipairs(mod.items) do
1112 if item.type == 'function' and not item.ret then
1113 print(mod.name,item.name,mod.file,item.lineno)
1114 end
1115 end
1116 end
1117 end
1118 }
1119
1120 The internal naming is not always so consistent; `ret` corresponds to @return, and `params`
1121 corresponds to @param. `item.params` is an array of the function parameters, in order; it
1122 is also a map from these names to the individual descriptions of the parameters.
1123
1124 `item.modifiers` is a table where the keys are the tags and the values are arrays of
1125 modifier tables. The standard tag aliases `tparam` and `treturn` attach a `type` modifier
1126 to their tags.
1127
1128
+0
-1129
docs/doc.md less more
0 # LDoc, a Lua Documentation Tool
1
2 @lookup doc.md
3
4 ## Introduction
5
6 LDoc is a second-generation documentation tool that can be used as a replacement for
7 [LuaDoc](http://keplerproject.github.com/luadoc/). It arose out of my need to document my
8 own projects and only depends on the [Penlight](https://github.com/stevedonovan/Penlight)
9 libraries.
10
11 It is mostly compatible with LuaDoc, except that certain workarounds are no longer needed.
12 For instance, it is not so married to the idea that Lua modules should be defined using the
13 `module` function; this is not only a matter of taste since this has been deprecated in Lua
14 5.2.
15
16 Otherwise, the output is very similar, which is no accident since the HTML templates are
17 based directly on LuaDoc. You can ship your own customized templates and style sheets with
18 your [own project](http://nilnor.github.com/textui/docs/), however. You have an option to
19 use Markdown to process the documentation, which means no ugly HTML is needed in doc
20 comments. C/C++ extension modules may be documented in a similar way, although function
21 names cannot be inferred from the code itself.
22
23 LDoc can provide integrated documentation, with traditional function comments, any documents
24 in Markdown format, and specified source examples. Lua source in examples and the documents
25 will be prettified.
26
27 Although there are a fair number of command-line options, the preferred route is to write a
28 `config.ld` configuration file in Lua format. By convention, if LDoc is simply invoked as
29 `ldoc .` it will read this file first. In this way, the aim is to make it very easy for
30 end-users to build your documentation using this simple command.
31
32 ## Commenting Conventions
33
34 LDoc follows the conventions established by Javadoc and later by LuaDoc.
35
36 Only 'doc comments' are parsed; these can be started with at least 3 hyphens, or by a empty
37 comment line with at least 3 hypens:
38
39 --- summary.
40 -- Description; this can extend over
41 -- several lines
42
43 -----------------
44 -- This will also do.
45
46 You can also use Lua block comments:
47
48 --[[--
49 Summary. A description
50 ...;
51 ]]
52
53 Any module or script must start with a doc comment; any other files are ignored and a
54 warning issued. The only exception is if the module starts with an explicit `module`
55 statement.
56
57 All doc comments start with a summary sentence, that ends with a period or a question mark.
58 An optional description may follow. Normally the summary sentence will appear in the module
59 contents.
60
61 After this descriptive text, there will typically be _tags_. These follow the convention
62 established by Javadoc and widely used in tools for other languages.
63
64 --- foo explodes text.
65 -- It is a specialized splitting operation on a string.
66 -- @param text the string
67 -- @return a table of substrings
68 function foo (text)
69 ....
70 end
71
72 There are also 'tparam' and 'treturn' which let you [specify a type](#Tag_Modifiers):
73
74 -- @tparam string text the string
75 -- @treturn {string,...} a table of substrings
76
77 There may be multiple 'param' tags, which should document each formal parameter of the
78 function. For Lua, there can also be multiple 'return' tags
79
80 --- solvers for common equations.
81 module("solvers", package.seeall)
82
83 --- solve a quadratic equation.
84 -- @param a first coeff
85 -- @param b second coeff
86 -- @param c third coeff
87 -- @return first root, or nil
88 -- @return second root, or imaginary root error
89 function solve (a,b,c)
90 local disc = b^2 - 4*a*c
91 if disc < 0 then
92 return nil,"imaginary roots"
93 else
94 disc = math.sqrt(disc)
95 return (-b + disc)/2*a,
96 (-b - disc)/2*a
97 end
98 end
99
100 ...
101
102 This is the common module style used in Lua 5.1, but it's increasingly common to see less
103 'magic' ways of creating modules in Lua. Since `module` is deprecated in Lua 5.2, any
104 future-proof documentation tool needs to handle these styles gracefully:
105
106 --- a test module
107 -- @module test
108
109 local test = {}
110
111 --- first test.
112 function test.one()
113 ...
114 end
115
116 ...
117
118 return test
119
120 Here the name of the module is explicitly given using the 'module' tag. If you leave this
121 out, then LDoc will infer the name of the module from the name of the file and its relative
122 location in the filesystem; this logic is also used for the `module(...)` idiom. (How this
123 works and when you need to provide extra information is discussed later.)
124
125 It is common to use a local name for a module when declaring its contents. In this case the
126 'alias' tag can tell LDoc that these functions do belong to the module:
127
128 --- another test.
129 -- @module test2
130 -- @alias M
131
132 local M = {}
133
134 -- first test.
135 function M.one()
136 ..
137 end
138
139 return M
140
141 `M` and `_M` are used commonly enough that LDoc will recognize them as aliases
142 automatically, but 'alias' allows you to use any identifier.
143
144 LDoc tries to deduce the function name and the formal parameter names from examining the
145 code after the doc comment. It also recognizes the 'unsugared' way of defining functions as
146 explicit assignment to a variable:
147
148 --- second test.
149 M.two = function(...) ... end
150
151 Apart from exported functions, a module usually contains local functions. By default, LDoc
152 does not include these in the documentation, but they can be enabled using the `--all` flag.
153 They can be documented just like 'public' functions:
154
155 --- it's clear that boo is local from context.
156 local function boo(...) .. end
157
158 local foo
159
160 --- we need to give a hint here for foo
161 -- @local here
162 function foo(...) .. end
163
164 Modules can of course export tables and other values. The classic way to document a table
165 looks like this:
166
167 --- a useful table of constants
168 -- @field alpha first correction
169 -- @field beta second correction
170 -- @field gamma fudge factor
171 -- @table constants
172
173 Here the kind of item is made explicit by the 'table' tag; tables have 'fields' in the same
174 way as functions have parameters.
175
176 This can get tedious, so LDoc will attempt to extract table documentation from code:
177
178 --- a useful table of constants
179 M.constants = {
180 alpha = 0.23, -- first correction
181 beta = 0.443, -- second correction
182 gamma = 0.01 -- fudge factor
183 }
184
185 The rule followed here is `NAME = <table-constructor>`. If LDoc can't work out the name and
186 type from the following code, then a warning will be issued, pointing to the file and
187 location.
188
189 Another kind of module-level type is 'field', such as follows:
190
191 --- module version.
192 M._VERSION = '0.5'
193
194 That is, a module may contain exported functions, local functions, tables and fields.
195
196 When the code analysis would lead to the wrong type, you can always be explicit.
197
198 --- module contents.
199 -- @field _CONTENTS
200 M._CONTENTS = {constants=true,one=true,...}
201
202 The order of tags is not important, but as always, consistency is useful. Tags like 'param'
203 and 'return' can be specified multiple times, whereas a type tag like 'function' can only
204 occur once in a comment. The basic rule is that a single doc comment can only document one
205 entity.
206
207 By default, LDoc will process any file ending in '.lua' or '.luadoc' in a specified
208 directory; you may point it to a single file as well. A 'project' usually consists of many
209 modules in one or more _packages_. The generated `index.html` will point to the generated
210 documentation for each of these modules.
211
212 If only one module or script is documented for a project, then the `index.html` generated
213 contains the documentation for that module, since an index pointing to one module would be
214 redundant.
215
216 (If you want to document a script, there is a project-level type 'script' for that.)
217
218 ## See References
219
220 The tag 'see' is used to reference other parts of the documentation, and 'usage' can provide
221 examples of use:
222
223 ---------
224 -- split a string in two.
225 -- @param s the string
226 -- @param delim the delimiter (default space)
227 -- @return first part
228 -- @return second part
229 -- @usage local hello,world = split2("hello world")
230 -- @see split
231 funtion split2(s,delim) .. end
232
233 Here it's assumed that 'split' is a function defined in the same module. If you wish to link
234 to a function in another module, then the reference has to be qualified.
235
236 References to methods use a colon: `myclass:method`; this is for instance how you would
237 refer to members of a `@type` section.
238
239 The example at `tests/complex` shows how @see references are interpreted:
240
241 complex.util.parse
242 complex.convert.basic
243 complex.util
244 complex.display
245 complex
246
247 You may of course use the full name of a module or function, but can omit the top-level
248 namespace - e.g. can refer to the module `util` and the function `display.display_that`
249 directly. Within a module, you can directly use a function name, e.g. in `display` you can
250 say `display_this`.
251
252 What applies to functions also applies to any module-level item like tables. New
253 module-level items can be defined and they will work according to these rules.
254
255 If a reference is not found within the project, LDoc checks to see if it is a reference to a
256 Lua standard function or table, and links to the online Lua manual. So references like
257 'table.concat' are handled sensibly.
258
259 References may be made inline using the @\{ref} syntax. This may appear anywhere in the
260 text, and is more flexible than @see. In particular, it provides one way to document the
261 type of a parameter or return value when that type has a particular structure:
262
263 ------
264 -- extract standard variables.
265 -- @param s the string
266 -- @return @\{stdvars}
267 function extract_std(s) ... end
268
269 ------
270 -- standard variables.
271 -- Use @\{extract_std} to parse a string containing variables,
272 -- and @\{pack_std} to make such a string.
273 -- @field length
274 -- @field duration
275 -- @field viscosity
276 -- @table stdvars
277
278 @\{ref} is very useful for referencing your API from code samples and readme text. (I've had
279 to throw in a spurious backspace to stop expansion in this example.)
280
281 The link text can be changed from the default by the extended syntax @\{ref|text}.
282
283 You can also put references in backticks, like `\`stdvars\``. This is commonly used in
284 Markdown to indicate code, so it comes naturally when writing documents. It is controlled by
285 the configuration variable `backtick_references`; the default is `true` if you use Markdown
286 in your project, but can be specified explicitly in your `config.ld`.
287
288 ### Custom @see References
289
290 It's useful to define how to handle references external to a project. For instance, in the
291 [luaposix](https://github.com/luaposix/luaposix) project we wanted to have `man` references
292 to the corresponding C function:
293
294 ------------
295 -- raise a signal on this process.
296 -- @see raise(3)
297 -- @int nsig
298 -- @return integer error cod
299 function raise (nsig)
300 end
301
302 These see references always have this particular form, and the task is to turn them into
303 online references to the Linux manpages. So in `config.ld` we have:
304
305 local upat = "http://www.kernel.org/doc/man-pages/online/pages/man%s/%s.%s.html"
306
307 custom_see_handler('^(%a+)%((%d)%)$',function(name,section)
308 local url = upat:format(section,name,section)
309 local name = name .. '(' ..section..')'
310 return name, url
311 end)
312
313 '^(%a+)%((%d)%)$' both matches the pattern and extracts the name and its section. THen it's
314 a simple matter of building up the appropriate URL. The function is expected to
315 return _link text_ and _link source_ and the patterns are checked before LDoc tries to resolve
316 project references. So it is best to make them match as exactly as possible.
317
318 ## Sections
319
320 LDoc supports _explicit_ sections. By default, the sections correspond to the pre-existing
321 types in a module: 'Functions', 'Tables' and 'Fields' (There is another default section
322 'Local Functions' which only appears if LDoc is invoked with the `--all` flag.) But new
323 sections can be added; the first mechanism is when you define a new type (say 'macro') a new
324 section ('Macros') is created to contain these types. There is also a way to declare ad-hoc
325 sections using the `@section` tag.
326
327 The need occurs when a module has a lot of functions that need to be put into logical
328 sections.
329
330 --- File functions.
331 -- Useful utilities for opening foobar format files.
332 -- @section file
333
334 --- open a file
335 ...
336
337 --- read a file
338 ...
339
340 --- Encoding operations.
341 -- Encoding foobar output in different ways.
342 -- @section encoding
343
344 ...
345
346 A section doc-comment has the same structure as a normal doc-comment; the summary is used as
347 the new section title, and the description will be output at the start of the function
348 details for that section.
349
350 In any case, sections appear under 'Contents' on the left-hand side. See the
351 [winapi](http://stevedonovan.github.com/winapi/api.html) documentation for an example of how
352 this looks.
353
354 Arguably a module writer should not write such very long modules, but it is not the job of
355 the documentation tool to limit the programmer!
356
357 A specialized kind of section is `type`: it is used for documenting classes. The functions
358 (or fields) within a type section are considered to be the methods of that class.
359
360 --- A File class.
361 -- @type File
362
363 ....
364 --- get the modification time.
365 -- @return standard time since epoch
366 function File:mtime()
367 ...
368 end
369
370 (In an ideal world, we would use the word 'class' instead of 'type', but this would conflict
371 with the LuaDoc usage.)
372
373 A section continues until the next section is found, `@section end`, or end of file.
374
375 You can put items into an implicit section using the @within tag. This allows you to put
376 adjacent functions in different sections, so that you are not forced to order your code
377 in a particular way.
378
379 Sometimes a module may logically span several files. There will be a master module with name
380 'foo' and other files which when required add functions to that module. If these files have
381 a @submodule tag, their contents will be placed in the master module documentation. However,
382 a current limitation is that the master module must be processed before the submodules.
383
384 See the `tests/submodule` example for how this works in practice.
385
386 ## Differences from LuaDoc
387
388 LDoc only does 'module' documentation, so the idea of 'files' is redundant.
389
390 One added convenience is that it is easier to name entities:
391
392 ------------
393 -- a simple module.
394 -- (LuaDoc)
395 -- @class module
396 -- @name simple
397
398 ------------
399 -- a simple module.
400 -- (LDoc)
401 -- @module simple
402
403 This is because type names (like 'function', 'module', 'table', etc) can function as tags.
404 LDoc also provides a means to add new types (e.g. 'macro') using a configuration file which
405 can be shipped with the source. If you become bored with typing 'param' repeatedly then you
406 can define an alias for it, such as 'p'. This can also be specified in the configuration file.
407
408 LDoc will also work with C/C++ files, since extension writers clearly have the same
409 documentation needs as Lua module writers.
410
411 LDoc allows you to attach a _type_ to a parameter or return value
412
413 --- better mangler.
414 -- @tparam string name
415 -- @int max length
416 -- @treturn string mangled name
417 function strmangler(name,max)
418 ...
419 end
420
421 `int` here is short for `tparam int` (see @{Tag_Modifiers})
422
423 It's common for types to be optional, or have different types, so the type can be like
424 '?int|string' which renders as '(int or string)', or '?int', which renders as
425 '(optional int)'.
426
427 LDoc gives the documenter the option to use Markdown to parse the contents of comments.
428
429 Since 1.3, LDoc allows the use of _colons_ instead of @.
430
431 --- a simple function.
432 -- string name person's name
433 -- int: age age of person
434 -- !person: person object
435 -- treturn: ?string
436 -- function check(name,age)
437
438 However, you must either use the `--colon` flag or set `colon=true` in your `config.ld`.
439
440 In this style, types may be used directly if prefixed with '!' or '?' (for type-or-nil)
441
442 (see `tests/styles/colon.lua`)
443
444 ## Adding new Tags
445
446 LDoc tries to be faithful to LuaDoc, but provides some extensions. Aliases for tags can be
447 defined, and new types declared.
448
449 --- zero function. Two new ldoc features here; item types
450 -- can be used directly as tags, and aliases for tags
451 -- can be defined in config.ld.
452 -- @function zero_fun
453 -- @p k1 first
454 -- @p k2 second
455
456 Here an alias for 'param' has been defined. If a file `config.ld` is found in the source,
457 then it will be loaded as Lua data. For example, the configuration for the above module
458 provides a title and defines an alias for 'param':
459
460 title = "testmod docs"
461 project = "testmod"
462 alias("p","param")
463
464 Extra tag _types_ can be defined:
465
466 new_type("macro","Macros")
467
468 And then used as any other type:
469
470 -----
471 -- A useful macro. This is an example of a custom type.
472 -- @macro first_macro
473 -- @see second_function
474
475 This will also create a new module section called 'Macros'.
476
477 If your new type has arguments or fields, then specify the name:
478
479 new_type("macro","Macros",false,"param")
480
481 (The third argument means that this is not a _project level_ tag)
482
483 Then you may say:
484
485 -----
486 -- A macro with arguments.
487 -- @macro second_macro
488 -- @param x the argument
489
490 And the arguments will be displayed under the subsection 'param'
491
492
493 ## Inferring more from Code
494
495 The qualified name of a function will be inferred from any `function` keyword following the
496 doc comment. LDoc goes further with this kind of code analysis, however.
497
498 Instead of:
499
500 --- first table.
501 -- @table one
502 -- @field A alpha
503 -- @field B beta
504 M.one = {
505 A = 1,
506 B = 2;
507 }
508
509 you can write:
510
511 --- first table
512 -- @table one
513 M.one = {
514 A = 1, -- alpha
515 B = 2; -- beta
516 }
517
518 Simularly, function parameter comments can be directly used:
519
520 ------------
521 -- third function. Can also provide parameter comments inline,
522 -- provided they follow this pattern.
523 function mod1.third_function(
524 alpha, -- correction A
525 beta, -- correction B
526 gamma -- factor C
527 )
528 ...
529 end
530
531 As always, explicit tags can override this behaviour if it is inappropriate.
532
533 ## Extension modules written in C
534
535 LDoc can process C/C++ files:
536
537 @plain
538 /***
539 Create a table with given array and hash slots.
540 @function createtable
541 @param narr initial array slots, default 0
542 @param nrec initial hash slots, default 0
543 @return the new table
544 */
545 static int l_createtable (lua_State *L) {
546 ....
547
548 Both `/**` and `///` are recognized as starting a comment block. Otherwise, the tags are
549 processed in exactly the same way. It is necessary to specify that this is a function with a
550 given name, since this cannot be reliably be inferred from code. Such a file will need a
551 module comment, which is treated exactly as in Lua.
552
553 An unknown extension can be associated with a language using a call like
554 `add_language_extension('lc','c')` in `config.ld`. (Currently the language can only be 'c'
555 or 'lua'.)
556
557 An LDoc feature which is particularly useful for C extensions is _module merging_. If several
558 files are all marked as `@module lib` then a single module `lib` is generated, containing all
559 the docs from the separate files.
560
561 See 'tests/examples/mylib.c' for the full example.
562
563 ## Basic Usage
564
565 For example, to process all files in the 'lua' directory:
566
567 $ ldoc lua
568 output written to docs/
569
570 Thereafter the `docs` directory will contain `index.html` which points to individual modules
571 in the `modules` subdirectory. The `--dir` flag can specify where the output is generated,
572 and will ensure that the directory exists. The output structure is like LuaDoc: there is an
573 `index.html` and the individual modules are in the `modules` subdirectory. This applies to
574 all project-level types, so that you can also get `scripts`, `examples` and `topics`
575 directories.
576
577 If your modules use `module(...)` then the module name has to be deduced. If `ldoc` is run
578 from the root of the package, then this deduction does not need any help - e.g. if your
579 package was `foo` then `ldoc foo` will work as expected. If we were actually in the `foo`
580 directory then `ldoc -b .. .` will correctly deduce the module names. An example would be
581 generating documentation for LuaDoc itself:
582
583 $ ldoc -b .. /path/to/luadoc
584
585 Without the `-b` setting the base of the package to the _parent_ of the directory, implicit
586 modules like `luadoc.config` will be incorrectly placed in the global namespace.
587
588 For new-style modules, that don't use `module()`, it is recommended that the module comment
589 has an explicit `@module PACKAGE.NAME`. If it does not, then `ldoc` will still attempt to
590 deduce the module name, but may need help with `--package/-b` as above.
591
592 `format = 'markdown'` can be used in your `config.ld` and will be used to process summaries
593 and descriptions. This requires [markdown.lua](http://www.frykholm.se/files/markdown.lua) by
594 Niklas Frykholm to be installed (this can be most easily done with `luarocks install
595 markdown`.) A much faster alternative is
596 [lua-discount](http://asbradbury.org/projects/lua-discount/) which you can use by setting
597 `format` to 'discount' after installing using `luarocks install lua-discount`) The
598 [discount](http://www.pell.portland.or.us/~orc/Code/discount/) Markdown processor
599 additionally has more features than the pure Lua version, such as PHP-Extra style tables.
600 As a special case, LDoc will fall back to using `markdown.lua` if it cannot find `discount`.
601
602 `format = 'markdown'` can be used in your `config.ld` and will be used to process summaries
603 and descriptions. This requires a markdown processor.
604 LDoc knows how to use:
605
606 - [markdown.lua](http://www.frykholm.se/files/markdown.lua) a pure Lua processor by
607 Niklas Frykholm (this can be installed easily with `luarocks install markdown`.)
608 - [lua-discount](http://asbradbury.org/projects/lua-discount/), a faster alternative
609 (installed with `luarocks install lua-discount`). lua-discount uses the C
610 [discount](http://www.pell.portland.or.us/~orc/Code/discount/) Markdown processor which has
611 more features than the pure Lua version, such as PHP-Extra style tables.
612 - [lunamark](http://jgm.github.com/lunamark/), another pure Lua processor, faster than
613 markdown, and with extra features (`luarocks install lunamark`).
614
615 You can request the processor you like with `format = 'markdown|discount|lunamark'`, and
616 LDoc will attempt to use it. If it can't find it, it will look for one of the other
617 markdown processors. If it can't find any markdown processer, it will fall back to text
618 processing.
619
620
621 A special case is if you simply say 'ldoc .'. Then there _must_ be a `config.ld` file
622 available in the directory, and it can specify the file:
623
624 file = "mymod.lua"
625 title = "mymod documentation"
626 description = "mymod does some simple but useful things"
627
628 `file` can of course point to a directory, just as with the `--file` option. This mode makes
629 it particularly easy for the user to build the documentation, by allowing you to specify
630 everything explicitly in the configuration.
631
632 In `config.ld`, `file` may be a Lua table, containing file names or directories; if it has
633 an `exclude` field then that will be used to exclude files from the list, for example
634 `{'examples', exclude = {'examples/slow.lua'}}`.
635
636
637 ## Processing Single Modules
638
639 `--output` can be used to give the output file a different name. This is useful for the
640 special case when a single module file is specified. Here an index would be redundant, so
641 the single HTML file generated contains the module documentation.
642
643 $ ldoc mylib.lua --> results in docs/index.html
644 $ ldoc --output mylib mylib.lua --> results in docs/mylib.html
645 $ ldoc --output mylib --dir html mylib.lua --> results in html/mylib.html
646
647 The default sections used by LDoc are 'Functions', 'Tables' and 'Fields', corresponding to
648 the built-in types 'function', 'table' and 'field'. If `config.ld` contains something like
649 `new_type("macro","Macros")` then this adds a new section 'Macros' which contains items of
650 'macro' type - 'macro' is registered as a new valid tag name. The default template then
651 presents items under their corresponding section titles, in order of definition.
652
653 ## Getting Help about a Module
654
655 There is an option to simply dump the results of parsing modules. Consider the C example
656 `tests/example/mylib.c':
657
658 @plain
659 $ ldoc --dump mylib.c
660 ----
661 module: mylib A sample C extension.
662 Demonstrates using ldoc's C/C++ support. Can either use /// or /*** */ etc.
663
664 function createtable(narr, nrec)
665 Create a table with given array and hash slots.
666 narr initial array slots, default 0
667 nrec initial hash slots, default 0
668
669 function solve(a, b, c)
670 Solve a quadratic equation.
671 a coefficient of x^2
672 b coefficient of x
673 c constant
674 return {"first root","second root"}
675
676 This is useful to quickly check for problems; here we see that `createable` did not have a
677 return tag.
678
679 LDoc takes this idea of data dumping one step further. If used with the `-m` flag it will
680 look up an installed Lua module and parse it. If it has been marked up in LuaDoc-style then
681 you will get a handy summary of the contents:
682
683 @plain
684 $ ldoc -m pl.pretty
685 ----
686 module: pl.pretty Pretty-printing Lua tables.
687 * read(s) - read a string representation of a Lua table.
688 * write(tbl, space, not_clever) - Create a string representation of a Lua table.
689
690 * dump(t, ...) - Dump a Lua table out to a file or stdout.
691
692 You can specify a fully qualified function to get more information:
693
694 @plain
695 $ ldoc -m pl.pretty.write
696
697 function write(tbl, space, not_clever)
698 create a string representation of a Lua table.
699 tbl {table} Table to serialize to a string.
700 space {string} (optional) The indent to use.
701 Defaults to two spaces.
702 not_clever {bool} (optional) Use for plain output, e.g {['key']=1}.
703 Defaults to false.
704
705 LDoc knows about the basic Lua libraries, so that it can be used as a handy console reference:
706
707 @plain
708 $> ldoc -m assert
709
710 function assert(v, message)
711 Issues an error when the value of its argument `v` is false (i.e.,
712 nil or false); otherwise, returns all its arguments.
713 `message` is an error
714 message; when absent, it defaults to "assertion failed!"
715 v
716 message
717
718 Thanks to Mitchell's [Textadept](http://foicica.com/textadept/) project, LDoc has a
719 set of `.luadoc` files for all the standard tables, plus
720 [LuaFileSystem](http://keplerproject.github.com/luafilesystem/) and
721 [LPeg](http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html).
722
723 @plain
724 $> ldoc -m lfs.lock
725
726 function lock(filehandle, mode, start, length)
727 Locks a file or a part of it.
728 This function works on open files; the file
729 handle should be specified as the first argument. The string mode could be
730 either r (for a read/shared lock) or w (for a write/exclusive lock). The
731 optional arguments start and length can be used to specify a starting point
732 and its length; both should be numbers.
733 Returns true if the operation was successful; in case of error, it returns
734 nil plus an error string.
735 filehandle
736 mode
737 start
738 length
739
740 ## Anatomy of a LDoc-generated Page
741
742 [winapi](http://stevedonovan.github.com/winapi/api.html) can be used as a good example of a
743 module that uses extended LDoc features.
744
745 The _navigation section_ down the left has several parts:
746
747 - The project name ('project' in the config)
748 - A project description ('description')
749 - ''Contents'' of the current page
750 - ''Modules'' listing all the modules in this project
751
752 Note that `description` will be passed through Markdown, if it has been specified for the
753 project. This gives you an opportunity to make lists of links, etc; any '##' headers will be
754 formatted like the other top-level items on the navigation bar.
755
756 'Contents' is automatically generated. It will contain any explicit sections, if they have
757 been used. Otherwise you will get the usual categories: 'Functions', 'Tables' and 'Fields'.
758
759 'Modules' will appear for any project providing Lua libraries; there may also be a 'Scripts'
760 section if the project contains Lua scripts. For example,
761 [LuaMacro](http://stevedonovan.github.com/LuaMacro/docs/api.html) has a driver script `luam`
762 in this section. The
763 [builtin](http://stevedonovan.github.com/LuaMacro/docs/modules/macro.builtin.html) module
764 only defines macros, which are defined as a _custom tag type_.
765
766 The _content section_ on the right shows:
767
768 - The module summary and description
769 - The contents summary, per section as above
770 - The detailed documentation for each item
771
772 As before, the description can use Markdown. The summary contains the contents of each
773 section as a table, with links to the details. This is where the difference between an
774 item's summary and an item's description is important; the first will appear in the contents
775 summary. The item details show the item name and its summary again, followed by the
776 description. There are then sections for the following tags: 'param', 'usage', 'return' and
777 'see' in that order. (For tables, 'Fields' is used instead of 'Parameters' but internally
778 fields of a table are stored as the 'param' tag.)
779
780 You can of course customize the default template, but there are some parameters that can
781 control what the template will generate. Setting `one` to `true` in your configuration file
782 will give a _one-column_ layout, which can be easier to use as a programming reference. You
783 can suppress the contents summary with `no_summary`.
784
785 ## Customizing the Page
786
787 Setting `no_return_or_parms` to `true` will suppress the display of 'param' and 'return'
788 tags. This may appeal to programmers who dislike the traditional @tag soup xDoc style and
789 prefer to comment functions just with a description. This is particularly useful when using
790 Markdown in a stylized way to specify arguments:
791
792 ---------
793 -- This extracts the shortest common substring from the strings _s1_ and _s2_
794 function M.common_substring(s1,s2)
795
796 Here I've chosen to italicise parameter names; the main thing is to be consistent.
797
798 This style is close to the Python [documentation
799 standard](http://docs.python.org/library/array.html#module-array), especially when used with
800 `no_summary`.
801
802 It is also very much how the Lua documentation is ordered. For instance, this configuration
803 file formats the built-in documentation for the Lua global functions in a way which is close
804 to the original:
805
806 project = 'Lua'
807 description = 'Lua Standard Libraries'
808 file = {'ldoc/builtin',exclude = {'ldoc/builtin/globals.lua'}}
809 no_summary = true
810 no_return_or_parms = true
811 format = 'discount'
812
813
814 Generally, using Markdown gives you the opportunity to structure your documentation in any
815 way you want; particularly if using lua-discount and its [table
816 syntax](http://michelf.com/projects/php-markdown/extra/#table); the desired result can often
817 be achieved then by using a custom style sheet.
818
819 ## Examples
820
821 It has been long known that documentation generated just from the source is not really
822 adequate to explain _how_ to use a library. People like reading narrative documentation,
823 and they like looking at examples. Previously I found myself dealing with source-generated
824 and writer-generated documentation using different tools, and having to match these up.
825
826 LDoc allows for source examples to be included in the documentation. For example, see the
827 online documentation for [winapi](http://stevedonovan.github.com/winapi/api.html). The
828 function `utf8_expand` has a `@see` reference to 'testu.lua' and following that link gives
829 you a pretty-printed version of the code.
830
831 The line in the `config.ld` that enables this is:
832
833 examples = {'examples', exclude = {'examples/slow.lua'}}
834
835 That is, all files in the `examples` folder are to be pretty-printed, except for `slow.lua`
836 which is meant to be called from one of the examples. The see-reference to `testu.lua`
837 resolves to 'examples/testu.lua.html'.
838
839 Examples may link back to the API documentation, for instance the example `input.lua` has a
840 @\{spawn_process} inline reference.
841
842 ## Readme files
843
844 Like all good Github projects, Winapi has a `readme.md`:
845
846 readme = "readme.md"
847
848 This goes under the 'Topics' global section; the 'Contents' of this document is generated
849 from the second-level (##) headings of the readme.
850
851 Readme files are always processed with the current Markdown processor, but may also contain @\{} references back
852 to the documentation and to example files. Any symbols within backticks will be expanded as
853 references, if possible. As with doc comments, a link to a standard Lua function like
854 @\{os.execute} will work as well. Any code sections will be pretty-printed as Lua, unless
855 the first indented line is '@plain'. (See the source for this readme to see how it's used.)
856
857 Another name for `readme` is `topics`, which is more descriptive. From LDoc 1.2,
858 `readme/topics` can be a list of documents. These act as a top-level table-of-contents for
859 your documentation. Currently, if you want them in a particular order, then use names like
860 `01-introduction.md` etc which sort appropriately.
861
862 The first line of a document may be a Markdown `#` title. If so, then LDoc will regard the
863 next level as the subheadings, normally second-level `##`. But if the title is already
864 second-level, then third-level headings will be used `###`, and so forth. The implication is
865 that the first heading must be top-level relative to the headings that follow, and must
866 start at the first line.
867
868 A reference like @\{string.upper} is unambiguous, and will refer to the online Lua manual.
869 In a project like Penlight, it can get tedious to have to write out fully qualified names
870 like @\{pl.utils.printf}. The first simplification is to use the `package` field to resolve
871 unknown references, which in this case is 'pl'. (Previously we discussed how `package` is
872 used to tell LDoc where the base package is in cases where the module author wishes to
873 remain vague, but it does double-duty here.) A further level of simplification comes from
874 the @lookup directive in documents, which must start at the first column on its own line.
875 For instance, if I am talking about `pl.utils`, then I can say "@lookup utils" and
876 thereafter references like @\{printf} will resolve correctly.
877
878 If you look at the source for this document, you will see a `@lookup doc.md` which allows
879 direct references to sections like @{Readme_files|this}.
880
881 Remember that the default is for references in backticks to be resolved; unlike @
882 references, it is not an error if the reference cannot be found.
883
884 The _sections_ of a document (the second-level headings) are also references. This
885 particular section can be refered to as @\{doc.md.Resolving_References_in_Documents} - the
886 rule is that any non-alphabetic character is replaced by an underscore.
887
888
889 ## Tag Modifiers
890
891 Ay tag may have _tag modifiers_. For instance, you may say
892 @\param[type=number] and this associates the modifier `type` with value `number` with this
893 particular param tag. A shorthand can be introduced for this common case, which is "@tparam
894 <type> <parmname> <comment>"; in the same way @\treturn is defined.
895
896 This is useful for larger projects where you want to provide the argument and return value
897 types for your API, in a structured way that can be easily extracted later. There is a
898 useful function for creating new tags that can be used in `config.ld`:
899
900 tparam_alias('string','string')
901
902 That is, "@string" will now have the same meaning as "@tparam string".
903
904 From 1.3, the following standard type aliases are predefined:
905
906 * `string`
907 * `number`
908 * `int`
909 * `bool` Lua 'boolean' type
910 * `func` 'function' (using 'function' would conflict with the type)
911 * `tab` 'table'
912 * `thread`
913
914 The exact form of `<type>` is not defined, but here is a suggested scheme:
915
916 number -- a plain type
917 Bonzo -- a known type; a reference link will be generated
918 {string,number} -- a 'list' tuple, built from type expressions
919 {A=string,N=number} -- a 'struct' tuple, ditto
920 {Bonzo,...} -- an array of Bonzo objects
921 {[string]=Bonzo,...} -- a map of Bonzo objects with string keys
922 Array(Bonzo) -- (assuming that Array is a container)
923
924 Currently the `type` modifier is the only one known and used by LDoc when generating HTML
925 output. However, any other modifiers are allowed and are available for use with your own
926 templates or for extraction by your own tools.
927
928 The `alias` function within configuration files has been extended so that alias tags can be
929 defined as a tag plus a set of modifiers. So `tparam` is defined as:
930
931 alias('tparam',{'param',modifiers={type="$1"}})
932
933 As an extension, you're allowed to use '@param' tags in table definitions. This makes it
934 possible to use type alias like '@string' to describe fields, since they will expand to
935 'param'.
936
937 Another modifier understood by LDoc is `opt`. For instance,
938
939 ---- testing [opt]
940 -- @param one
941 -- @param[opt] two
942 -- @param three
943 -- @param[opt] four
944 function two (one,two,three,four)
945 end
946 ----> displayed as: two (one [, two], three [, four])
947
948 This modifier can also be used with type aliases. If a value is given for the modifier
949 then LDoc can present this as the default value for this optional argument.
950
951 --- a function with typed args.
952 -- If the Lua function has varargs, then
953 -- you may document an indefinite number of extra arguments!
954 -- @string name person's name
955 -- @int age
956 -- @string[opt='gregorian'] calender optional calendar
957 -- @int[opt=0] offset optional offset
958 -- @treturn string
959 function one (name,age,...)
960 end
961 ----> displayed as: one (name, age [, calender='gregorian' [, offset=0]])
962
963 (See `tests/styles/four.lua`)
964
965 ## Fields allowed in `config.ld`
966
967 These mostly have the same meaning as the corresponding parameters:
968
969 - `file` a file or directory containing sources. In `config.ld` this can also be a table
970 of files and directories.
971 - `project` name of project, used as title in top left
972 - `title` page title, default 'Reference'
973 - `package ` explicit base package name; also used for resolving references in documents
974 - `all` show local functions, etc as well in the docs
975 - `format` markup processor, can be 'plain' (default), 'markdown' or 'discount'
976 - `output` output name (default 'index')
977 - `dir` directory for output files (default 'docs')
978 - `ext` extension for output (default 'html')
979 - `one` use a one-column layout
980 - `style`, `template`: together these specify the directories for the style and and the
981 template. In `config.ld` they may also be `true`, meaning use the same directory as the
982 configuration file.
983
984 These only appear in `config.ld`:
985
986 - `description` a project description used under the project title
987 - `examples` a directory or file: can be a table
988 - `readme` name of readme file (to be processed with Markdown)
989 - `no_return_or_parms` don't show parameters or return values in output
990 - `backtick_references` whether references in backticks will be resolved
991 - `manual_url` point to an alternative or local location for the Lua manual, e.g.
992 'file:///D:/dev/lua/projects/lua-5.1.4/doc/manual.html'
993 - `one` use a one-column output format
994 - `no_summary` suppress the Contents summary
995
996 Available functions are:
997
998 - `alias(a,tag)` provide an alias `a` for the tag `tag`, for instance `p` as short for
999 `param`
1000 - `add_language_extension(ext,lang)` here `lang` may be either 'c' or 'lua', and `ext` is
1001 an extension to be recognized as this language
1002 - `add_section`
1003 - `new_type(tag,header,project_level)` used to add new tags, which are put in their own
1004 section `header`. They may be 'project level'.
1005 - `tparam_alias(name,type)` for instance, you may wish that `Object` means `@\tparam
1006 Object`.
1007 - `custom_see_handler(pattern,handler)`. If a reference matches `pattern`, then the
1008 extracted values will be passed to `handler`. It is expected to return link text
1009 and a suitable URI. (This match will happen before default processing.)
1010
1011 ## Annotations and Searching for Tags
1012
1013 Annotations are special tags that can be used to keep track of internal development status.
1014 The known annotations are 'todo', 'fixme' and 'warning'. They may occur in regular
1015 function/table doc comments, or on their own anywhere in the code.
1016
1017 --- Testing annotations
1018 -- @module annot1
1019 ...
1020 --- first function.
1021 -- @todo check if this works!
1022 function annot1.first ()
1023 if boo then
1024
1025 end
1026 --- @fixme what about else?
1027 end
1028
1029 Although not currently rendered by the template as HTML, they can be extracted by the
1030 `--tags` command, which is given a comma-separated list of tags to list.
1031
1032 @plain
1033 D:\dev\lua\LDoc\tests> ldoc --tags todo,fixme annot1.lua
1034 d:\dev\lua\ldoc\tests\annot1.lua:14: first: todo check if this works!
1035 d:\dev\lua\ldoc\tests\annot1.lua:19: first-fixme1: fixme what about else?
1036
1037
1038 ## Generating HTML
1039
1040 LDoc, like LuaDoc, generates output HTML using a template, in this case `ldoc_ltp.lua`. This
1041 is expanded by the powerful but simple preprocessor devised originally by [Rici
1042 Lake](http://lua-users.org/wiki/SlightlyLessSimpleLuaPreprocessor) which is now part of
1043 Penlight. There are two rules - any line starting with '#' is Lua code, which can also be
1044 embedded with '$(...)'.
1045
1046 <h2>Contents</h2>
1047 <ul>
1048 # for kind,items in module.kinds() do
1049 <li><a href="#$(no_spaces(kind))">$(kind)</a></li>
1050 # end
1051 </ul>
1052
1053 This is then styled with `ldoc.css`. Currently the template and stylesheet is very much
1054 based on LuaDoc, so the results are mostly equivalent; the main change that the template has
1055 been more generalized. The default location (indicated by '!') is the directory of `ldoc.lua`.
1056
1057 You may customize how you generate your documentation by specifying an alternative style
1058 sheet and/or template, which can be deployed with your project. The parameters are `--style`
1059 and `--template`, which give the directories where `ldoc.css` and `ldoc.ltp` are to be
1060 found. If `config.ld` contains these variables, they are interpreted slightly differently;
1061 if they are true, then it means 'use the same directory as config.ld'; otherwise they must
1062 be a valid directory relative to the ldoc invocation.
1063
1064 An example of fully customized documentation is `tests/example/style`: this is what you
1065 could call 'minimal Markdown style' where there is no attempt to tag things (except
1066 emphasizing parameter names). The narrative alone _can_ to be sufficient, if it is written
1067 appropriately.
1068
1069 Of course, there's no reason why LDoc must always generate HTML. `--ext` defines what output
1070 extension to use; this can also be set in the configuration file. So it's possible to write
1071 a template that converts LDoc output to LaTex, for instance. The separation of processing
1072 and presentation makes this kind of new application possible with LDoc.
1073
1074 ## Internal Data Representation
1075
1076 The `--dump` flag gives a rough text output on the console. But there is a more
1077 customizeable way to process the output data generated by LDoc, using the `--filter`
1078 parameter. This is understood to be a fully qualified function (module + name). For example,
1079 try
1080
1081 $ ldoc --filter pl.pretty.dump mylib.c
1082
1083 to see a raw dump of the data. (Simply using `dump` as the value here would be a shorthand
1084 for `pl.pretty.dump`.) This is potentially very powerful, since you may write arbitrary Lua
1085 code to extract the information you need from your project.
1086
1087 For instance, a file `custom.lua` like this:
1088
1089 return {
1090 filter = function (t)
1091 for _, mod in ipairs(t) do
1092 print(mod.type,mod.name,mod.summary)
1093 end
1094 end
1095 }
1096
1097 Can be used like so:
1098
1099 ~/LDoc/tests/example$ ldoc --filter custom.filter mylib.c
1100 module mylib A sample C extension.
1101
1102 The basic data structure is straightforward: it is an array of 'modules' (project-level
1103 entities, including scripts) which each contain an `item` array (functions, tables and so
1104 forth).
1105
1106 For instance, to find all functions which don't have a @return tag:
1107
1108 return {
1109 filter = function (t)
1110 for _, mod in ipairs(t) do
1111 for _, item in ipairs(mod.items) do
1112 if item.type == 'function' and not item.ret then
1113 print(mod.name,item.name,mod.file,item.lineno)
1114 end
1115 end
1116 end
1117 end
1118 }
1119
1120 The internal naming is not always so consistent; `ret` corresponds to @return, and `params`
1121 corresponds to @param. `item.params` is an array of the function parameters, in order; it
1122 is also a map from these names to the individual descriptions of the parameters.
1123
1124 `item.modifiers` is a table where the keys are the tags and the values are arrays of
1125 modifier tables. The standard tag aliases `tparam` and `treturn` attach a `type` modifier
1126 to their tags.
1127
1128
+2
-2
ldoc/doc.lua less more
2323 param = 'M', see = 'M', usage = 'ML', ['return'] = 'M', field = 'M', author='M';
2424 class = 'id', name = 'id', pragma = 'id', alias = 'id', within = 'id',
2525 copyright = 'S', summary = 'S', description = 'S', release = 'S', license = 'S',
26 fixme = 'S', todo = 'S', warning = 'S', raise = 'S',
26 fixme = 'S', todo = 'S', warning = 'S', raise = 'S', charset = 'S',
2727 ['local'] = 'N', export = 'N', private = 'N', constructor = 'N', static = 'N';
2828 -- project-level
2929 module = 'T', script = 'T', example = 'T', topic = 'T', submodule='T',
345345 -- is not empty.
346346
347347 function File:add_document_section(title)
348 local section = title:gsub('%A','_')
348 local section = title:gsub('%W','_')
349349 self:new_item {
350350 name = section,
351351 class = 'section',
+3
-3
ldoc/html/ldoc_ltp.lua less more
11 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
22 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
33 <html>
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
4 <meta http-equiv="Content-Type" content="text/html; charset=$(ldoc.doc_charset)"/>
55 <head>
66 <title>$(ldoc.title)</title>
77 <link rel="stylesheet" href="$(ldoc.css)" type="text/css" />
4949 # end
5050
5151
52 # if ldoc.no_summary and module then -- bang out the functions on the side
52 # if ldoc.no_summary and module and not ldoc.one then -- bang out the functions on the side
5353 # for kind, items in module.kinds() do
5454 <h2>$(kind)</h2>
5555 <ul>
248248 </div> <!-- id="content" -->
249249 </div> <!-- id="main" -->
250250 <div id="about">
251 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.3</a></i>
251 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.3.11</a></i>
252252 </div> <!-- id="about" -->
253253 </div> <!-- id="container" -->
254254 </body>
+12
-1
ldoc/html.lua less more
121121 else return name end
122122 end
123123
124 function ldoc.no_spaces(s) return (s:gsub('%A','_')) end
124 function ldoc.no_spaces(s)
125 s = s:gsub('%s*$','')
126 return (s:gsub('%W','_'))
127 end
125128
126129 function ldoc.titlecase(s)
127130 return (s:gsub('(%a)(%a*)',function(f,r)
166169 return names
167170 end
168171
172 local function set_charset (ldoc,m)
173 m = m or ldoc.module
174 ldoc.doc_charset = (m and m.tags.charset) or ldoc.charset
175 end
176
169177 local module_template,err = utils.readfile (path.join(args.template,ldoc.templ))
170178 if not module_template then
171179 quit("template not found at '"..args.template.."' Use -l to specify directory containing ldoc.ltp")
182190 ldoc.module = ldoc.single
183191 if ldoc.single and args.one then
184192 ldoc.kinds_allowed = {module = true, topic = true}
193 ldoc.one = true
185194 end
186195 ldoc.root = true
187196 if ldoc.module then
188197 ldoc.module.info = get_module_info(ldoc.module)
189198 end
199 set_charset(ldoc)
190200 local out,err = template.substitute(module_template,{
191201 ldoc = ldoc,
192202 module = ldoc.module,
225235 for m in modules() do
226236 ldoc.module = m
227237 ldoc.body = m.body
238 set_charset(ldoc)
228239 m.info = get_module_info(m)
229240 if ldoc.body and m.postprocess then
230241 ldoc.body = m.postprocess(ldoc.body)
+5
-1
ldoc/parse.lua less more
244244 local item_follows, tags, is_local, case
245245 if ldoc_comment then
246246 comment = table.concat(comment)
247
247 if comment:match '^%s*$' then
248 ldoc_comment = nil
249 end
250 end
251 if ldoc_comment then
248252 if first_comment then
249253 first_comment = false
250254 else
+19
-5
ldoc.lua less more
66 --
77 -- C/C++ support for Lua extensions is provided.
88 --
9 -- Available from LuaRocks as 'ldoc' and as a [Zip file](http://stevedonovan.github.com/files/ldoc-1.3.0.zip)
9 -- Available from LuaRocks as 'ldoc' and as a [Zip file](http://stevedonovan.github.com/files/ldoc-1.3.9.zip)
1010 --
1111 -- [Github Page](https://github.com/stevedonovan/ldoc)
1212 --
3434
3535 --- @usage
3636 local usage = [[
37 ldoc, a documentation generator for Lua, vs 1.3.1
37 ldoc, a documentation generator for Lua, vs 1.3.11
3838 -d,--dir (default docs) output directory
3939 -o,--output (default 'index') output name
4040 -v,--verbose verbose
4343 -m,--module module docs as text
4444 -s,--style (default !) directory for style sheet (ldoc.css)
4545 -l,--template (default !) directory for template (ldoc.ltp)
46 -1,--one use one-column output layout
4746 -p,--project (default ldoc) project name
4847 -t,--title (default Reference) page title
4948 -f,--format (default plain) formatting - can be markdown, discount or plain
5554 -C,--colon use colon style
5655 -B,--boilerplate ignore first comment in source files
5756 -M,--merge allow module merging
57 -S,--simple no return or params, no summary
58 -O,--one one-column output layout
5859 --dump debug output dump
5960 --filter (default none) filter output as Lua data (e.g pl.pretty.dump)
6061 --tags (default none) show all references to given tags, comma-separated
120121 ------- ldoc external API ------------
121122
122123 -- the ldoc table represents the API available in `config.ld`.
123 local ldoc = {}
124 local ldoc = { charset = 'UTF-8' }
124125 local add_language_extension
125126
126127 local function override (field)
182183 local ldoc_contents = {
183184 'alias','add_language_extension','new_type','add_section', 'tparam_alias',
184185 'file','project','title','package','format','output','dir','ext', 'topics',
185 'one','style','template','description','examples', 'pretty',
186 'one','style','template','description','examples', 'pretty', 'charset',
186187 'readme','all','manual_url', 'ignore', 'colon','boilerplate','merge', 'wrap',
187188 'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler',
188189 }
282283 args.file = abspath(args.file)
283284 end
284285 else
286 -- user-provided config file
287 if args.config ~= 'config.ld' then
288 local err
289 config_dir,err = read_ldoc_config(args.config)
290 if err then quit("no "..quote(args.config).." found") end
291 end
292 -- with user-provided file
285293 args.file = abspath(args.file)
286294 end
287295
292300 if type(source_dir) == 'string' and path.isfile(source_dir) then
293301 source_dir = path.splitpath(source_dir)
294302 end
303 source_dir = source_dir:gsub('[/\\]%.$','')
295304
296305 ---------- specifying the package for inferring module names --------
297306 -- If you use module(...), or forget to explicitly use @module, then
436445 end)
437446 end
438447
448 if args.simple then
449 ldoc.no_return_or_parms=true
450 ldoc.no_summary=true
451 end
452
439453 ldoc.readme = ldoc.readme or ldoc.topics
440454 if type(ldoc.readme) == 'string' then
441455 ldoc.readme = {ldoc.readme}
+2
-0
tests/styles/config/config.ld less more
0 no_return_or_parms=true
1 no_summary=true