Package list lua-ldoc / 70eaf2b
bumped to 1.4.0; doc updates and formatting Steve Donovan 8 years ago
6 changed file(s) with 71 addition(s) and 50 deletion(s). Raw diff Collapse all Expand all
55 file='../ldoc.lua'
66 dir='../out'
77 readme='doc.md'
8 examples = {'../tests/styles/colon.lua','../tests/styles/four.lua','../tests/example/mylib.c'}
9
213213 contains the documentation for that module, since an index pointing to one module would be
214214 redundant.
215215
216 (If you want to document a script, there is a project-level type 'script' for that.)
216 LDoc has a two-layer hierarchy; underneath the project, there are modules, scripts, classes
217 (containing code) and examples and 'topics' (containing documentation). These then contain
218 items like functions, tables, sections, and so forth.
219
220 If you want to document scripts, then use `@script` instead of `@module`. New with 1.4 is
221 `@classmod` which is a module which exports a single class.
222
217223
218224 ## See References
219225
256262 Lua standard function or table, and links to the online Lua manual. So references like
257263 'table.concat' are handled sensibly.
258264
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
265 References may be made inline using the `@{\ref}` syntax. This may appear anywhere in the
266 text, and is more flexible than `@see`. In particular, it provides one way to document the
261267 type of a parameter or return value when that type has a particular structure:
262268
263269 ------
264270 -- extract standard variables.
265271 -- @param s the string
266 -- @return @\{stdvars}
272 -- @return @{\stdvars}
267273 function extract_std(s) ... end
268274
269275 ------
270276 -- standard variables.
271 -- Use @\{extract_std} to parse a string containing variables,
272 -- and @\{pack_std} to make such a string.
277 -- Use @{\extract_std} to parse a string containing variables,
278 -- and @{\pack_std} to make such a string.
273279 -- @field length
274280 -- @field duration
275281 -- @field viscosity
276282 -- @table stdvars
277283
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}.
284 `@{\ref}` is very useful for referencing your API from code samples and readme text.
285
286 The link text can be changed from the default by the extended syntax `@{\ref|text}.
282287
283288 You can also put references in backticks, like `\`stdvars\``. This is commonly used in
284289 Markdown to indicate code, so it comes naturally when writing documents. It is controlled by
310315 return name, url
311316 end)
312317
313 '^(%a+)%((%d)%)$' both matches the pattern and extracts the name and its section. THen it's
318 '^(%a+)%((%d)%)$' both matches the pattern and extracts the name and its section. Then it's
314319 a simple matter of building up the appropriate URL. The function is expected to
315320 return _link text_ and _link source_ and the patterns are checked before LDoc tries to resolve
316321 project references. So it is best to make them match as exactly as possible.
317322
318323 ## Sections
319324
320 LDoc supports _explicit_ sections. By default, the sections correspond to the pre-existing
325 LDoc supports _explicit_ sections. By default, the implicit sections correspond to the pre-existing
321326 types in a module: 'Functions', 'Tables' and 'Fields' (There is another default section
322327 '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
328 sections can be added; the first mechanism is when you define a new type (say 'macro'). Then a new
329 section ('Macros') is created to contain these types.
330
331 There is also a way to declare ad-hoc sections using the `@section` tag.
327332 The need occurs when a module has a lot of functions that need to be put into logical
328333 sections.
329334
441446
442447 In this style, types may be used directly if prefixed with '!' or '?' (for type-or-nil)
443448
444 (see `tests/styles/colon.lua`)
449 (see @{colon.lua})
445450
446451 ## Adding new Tags
447452
560565 files are all marked as `@module lib` then a single module `lib` is generated, containing all
561566 the docs from the separate files. For this, use `merge=true`.
562567
563 See 'tests/examples/mylib.c' for the full example.
568 See @{mylib.c} for the full example.
564569
565570 ## Basic Usage
566571
627632
628633 You can request the processor you like with `format = 'markdown|discount|lunamark'`, and
629634 LDoc will attempt to use it. If it can't find it, it will look for one of the other
630 markdown processors.
635 markdown processors; the original `markdown.lua` ships with LDoc, although it's slow
636 for larger documents.
631637
632638 Even with the default of 'plain' some minimal processing takes place, in particular empty lines
633 are treated as line breaks.
639 are treated as line breaks. If 'process_backticks=true` then backticks will be
640 expanded into documentation links like `@{\ref}` and converted into `<code>ref</code>`
641 otherwise.
634642
635643 This formatting applies to all of a project, including any readmes and so forth. You may want
636644 Markdown for this 'narrative' documentation, but not for your code comments. `plain=true` will
842850 resolves to 'examples/testu.lua.html'.
843851
844852 Examples may link back to the API documentation, for instance the example `input.lua` has a
845 @\{spawn_process} inline reference.
853 `@{\spawn_process}` inline reference.
846854
847855 By default, LDoc uses a built-in Lua code 'prettifier'. See-references are allowed in comments,
848856 and also in code if they're enclosed in backticks.
860868 This goes under the 'Topics' global section; the 'Contents' of this document is generated
861869 from the second-level (##) headings of the readme.
862870
863 Readme files are always processed with the current Markdown processor, but may also contain @\{} references back
871 Readme files are always processed with the current Markdown processor, but may also contain `@{\ref}` references back
864872 to the documentation and to example files. Any symbols within backticks will be expanded as
865873 references, if possible. As with doc comments, a link to a standard Lua function like
866 @\{os.execute} will work as well. Any code sections will be pretty-printed as Lua, unless
874 `@{\os.execute}` will work as well. Any code sections will be pretty-printed as Lua, unless
867875 the first indented line is '@plain'. (See the source for this readme to see how it's used.)
868876
869877 Another name for `readme` is `topics`, which is more descriptive. From LDoc 1.2,
877885 that the first heading must be top-level relative to the headings that follow, and must
878886 start at the first line.
879887
880 A reference like @\{string.upper} is unambiguous, and will refer to the online Lua manual.
888 A reference like `@{\string.upper}` is unambiguous, and will refer to the online Lua manual.
881889 In a project like Penlight, it can get tedious to have to write out fully qualified names
882 like @\{pl.utils.printf}. The first simplification is to use the `package` field to resolve
890 like `@{\pl.utils.printf}`. The first simplification is to use the `package` field to resolve
883891 unknown references, which in this case is 'pl'. (Previously we discussed how `package` is
884892 used to tell LDoc where the base package is in cases where the module author wishes to
885893 remain vague, but it does double-duty here.) A further level of simplification comes from
886 the @lookup directive in documents, which must start at the first column on its own line.
887 For instance, if I am talking about `pl.utils`, then I can say "@lookup utils" and
888 thereafter references like @\{printf} will resolve correctly.
894 the `@lookup` directive in documents, which must start at the first column on its own line.
895 For instance, if I am talking about `pl.utils`, then I can say `@lookup utils` and
896 thereafter references like `@{\printf}` will resolve correctly.
889897
890898 If you look at the source for this document, you will see a `@lookup doc.md` which allows
891899 direct references to sections like @{Readme_files|this}.
894902 references, it is not an error if the reference cannot be found.
895903
896904 The _sections_ of a document (the second-level headings) are also references. This
897 particular section can be refered to as @\{doc.md.Resolving_References_in_Documents} - the
905 particular section can be refered to as `@{\doc.md.Resolving_References_in_Documents}` - the
898906 rule is that any non-alphabetic character is replaced by an underscore.
899907
900908
901909 ## Tag Modifiers
902910
903911 Ay tag may have _tag modifiers_. For instance, you may say
904 @\param[type=number] and this associates the modifier `type` with value `number` with this
905 particular param tag. A shorthand can be introduced for this common case, which is "@tparam
906 <type> <parmname> <comment>"; in the same way @\treturn is defined.
912 `@param[type=number]` and this associates the modifier `type` with value `number` with this
913 particular param tag. A shorthand can be introduced for this common case, which is `@tparam
914 <type> <parmname> <comment>`; in the same way `@treturn` is defined.
907915
908916 This is useful for larger projects where you want to provide the argument and return value
909917 types for your API, in a structured way that can be easily extracted later. There is a
972980 end
973981 ----> displayed as: one (name, age [, calender='gregorian' [, offset=0]])
974982
975 (See `tests/styles/four.lua`)
983 (See @{four.lua})
976984
977985 ## Fields allowed in `config.ld`
978986
979 These mostly have the same meaning as the corresponding parameters:
987 _Same meaning as the corresponding parameters:_
980988
981989 - `file` a file or directory containing sources. In `config.ld` this can also be a table
982990 of files and directories.
9951003 template. In `config.ld` they may also be `true`, meaning use the same directory as the
9961004 configuration file.
9971005 - `merge` allow documentation from different files to be merged into modules without
998 explicit @submodule tag
999
1000 These only appear in `config.ld`:
1001
1002 - `description` a project description used under the project title
1006 explicit @submodule tag
1007
1008 _These only appear in `config.ld`:_
1009
1010 - `description` a short project description used under the project title
1011 - `full_description` when you _really_ need a longer project description
10031012 - `examples` a directory or file: can be a table
10041013 - `readme` or `topics` readme files (to be processed with Markdown)
10051014 - `pretty` code prettify 'lua' (default) or 'lxsh'
10061015 - `charset` use if you want to override the UTF-8 default (also @charset in files)
1016 - `sort` set if you want all items in alphabetical order
10071017 - `no_return_or_parms` don't show parameters or return values in output
1008 - `backtick_references` whether references in backticks will be resolved
1018 - `backtick_references` whether references in backticks will be resolved. Happens by default
1019 when using Markdown. When explicit will expand non-references in backticks into `<code>` elements
10091020 - `plain` set to true if `format` is set but you don't want code comments processed
10101021 - `wrap` ??
10111022 - `manual_url` point to an alternative or local location for the Lua manual, e.g.
10131024 - `no_summary` suppress the Contents summary
10141025 - `custom_see_handler` function that filters see-references
10151026 - `not_luadoc` set to `true` if the docs break LuaDoc compatibility
1016
1017 Available functions are:
1027 - `no_space_before_args` set to `true` if you do not want a space between a function's name and its arguments.
1028 - `template_escape` overrides the usual '#' used for Lua code in templates. This needs to be changed if the output format is Markdown, for instance.
1029
1030 _Available functions are:_
10181031
10191032 - `alias(a,tag)` provide an alias `a` for the tag `tag`, for instance `p` as short for
10201033 `param`
10231036 - `add_section`
10241037 - `new_type(tag,header,project_level)` used to add new tags, which are put in their own
10251038 section `header`. They may be 'project level'.
1026 - `tparam_alias(name,type)` for instance, you may wish that `Object` means `@\tparam
1027 Object`.
1039 - `tparam_alias(name,type)` for instance, you may wish that `Object` becomes a new tag alias
1040 that means `@tparam Object`.
10281041 - `custom_see_handler(pattern,handler)`. If a reference matches `pattern`, then the
10291042 extracted values will be passed to `handler`. It is expected to return link text
10301043 and a suitable URI. (This match will happen before default processing.)
10581071
10591072 ## Generating HTML
10601073
1061 LDoc, like LuaDoc, generates output HTML using a template, in this case `ldoc_ltp.lua`. This
1074 LDoc, like LuaDoc, generates output HTML using a template, in this case `ldoc/html/ldoc_ltp.lua`. This
10621075 is expanded by the powerful but simple preprocessor devised originally by [Rici
1076 Lake](http://lua-users.org/wiki/SlightlyLessSimpleLuaPreprocessor) which is now part of
10631077 Lake](http://lua-users.org/wiki/SlightlyLessSimpleLuaPreprocessor) which is now part of
10641078 Penlight. There are two rules - any line starting with '#' is Lua code, which can also be
10651079 embedded with '$(...)'.
10911105 extension to use; this can also be set in the configuration file. So it's possible to write
10921106 a template that converts LDoc output to LaTex, for instance. The separation of processing
10931107 and presentation makes this kind of new application possible with LDoc.
1108
1109 From 1.4, LDoc has some limited support for generating Markdown output, although only
1110 for single files currently. Use `--ext md` for this. 'ldoc/html/ldoc_mdtp.lua' defines
1111 the template for Markdown.
10941112
10951113 ## Internal Data Representation
10961114
121121 end
122122
123123
124 -- annotation tags can appear anywhere in the code and may contain of these tags:
124 -- annotation tags can appear anywhere in the code and may contain any of these tags:
125125 known_tags._annotation_tags = {
126126 fixme = true, todo = true, warning = true
127127 }
253253 </div> <!-- id="content" -->
254254 </div> <!-- id="main" -->
255255 <div id="about">
256 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.3.12</a></i>
256 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.0</a></i>
257257 </div> <!-- id="about" -->
258258 </div> <!-- id="container" -->
259259 </body>
1414 -- inline <references> use same lookup as @see
1515 local function resolve_inline_references (ldoc, txt, item, plain)
1616 local res = (txt:gsub('@{([^}]-)}',function (name)
17 if name:match '^\\' then return '@{'..name:sub(2)..'}' end
1718 local qname,label = utils.splitv(name,'%s*|')
1819 if not qname then
1920 qname = name
3434
3535 --- @usage
3636 local usage = [[
37 ldoc, a documentation generator for Lua, vs 1.3.12
37 ldoc, a documentation generator for Lua, vs 1.4.0
3838 -d,--dir (default doc) output directory
3939 -o,--output (default 'index') output name
4040 -v,--verbose verbose
177177 end
178178
179179 function ldoc.manual_url (url)
180 global.set_manual_url(url)
180 global.set_manual_url(url)
181181 end
182182
183183 function ldoc.custom_see_handler(pat, handler)
184 doc.add_custom_see_handler(pat, handler)
184 doc.add_custom_see_handler(pat, handler)
185185 end
186186
187187 local ldoc_contents = {