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

bumped to 1.4.0; doc updates and formatting

This commit is contained in:
Steve Donovan 2013-08-23 13:50:34 +02:00
parent 7bb95e5e7d
commit 70eaf2be6f
6 changed files with 66 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/config.ld
View File

@ -6,3 +6,5 @@ backtick_references=false
file='../ldoc.lua' file='../ldoc.lua'
dir='../out' dir='../out'
readme='doc.md' readme='doc.md'
examples = {'../tests/styles/colon.lua','../tests/styles/four.lua','../tests/example/mylib.c'}

98
doc/doc.md
View File

@ -214,7 +214,13 @@ If only one module or script is documented for a project, then the `index.html`
contains the documentation for that module, since an index pointing to one module would be contains the documentation for that module, since an index pointing to one module would be
redundant. redundant.
(If you want to document a script, there is a project-level type 'script' for that.) LDoc has a two-layer hierarchy; underneath the project, there are modules, scripts, classes
(containing code) and examples and 'topics' (containing documentation). These then contain
items like functions, tables, sections, and so forth.
If you want to document scripts, then use `@script` instead of `@module`. New with 1.4 is
`@classmod` which is a module which exports a single class.
## See References ## See References
@ -257,29 +263,28 @@ If a reference is not found within the project, LDoc checks to see if it is a re
Lua standard function or table, and links to the online Lua manual. So references like Lua standard function or table, and links to the online Lua manual. So references like
'table.concat' are handled sensibly. 'table.concat' are handled sensibly.
References may be made inline using the @\{ref} syntax. This may appear anywhere in the References may be made inline using the `@{\ref}` syntax. This may appear anywhere in the
text, and is more flexible than @see. In particular, it provides one way to document the text, and is more flexible than `@see`. In particular, it provides one way to document the
type of a parameter or return value when that type has a particular structure: type of a parameter or return value when that type has a particular structure:
------ ------
-- extract standard variables. -- extract standard variables.
-- @param s the string -- @param s the string
-- @return @\{stdvars} -- @return @{\stdvars}
function extract_std(s) ... end function extract_std(s) ... end
------ ------
-- standard variables. -- standard variables.
-- Use @\{extract_std} to parse a string containing variables, -- Use @{\extract_std} to parse a string containing variables,
-- and @\{pack_std} to make such a string. -- and @{\pack_std} to make such a string.
-- @field length -- @field length
-- @field duration -- @field duration
-- @field viscosity -- @field viscosity
-- @table stdvars -- @table stdvars
@\{ref} is very useful for referencing your API from code samples and readme text. (I've had `@{\ref}` is very useful for referencing your API from code samples and readme text.
to throw in a spurious backspace to stop expansion in this example.)
The link text can be changed from the default by the extended syntax @\{ref|text}. The link text can be changed from the default by the extended syntax `@{\ref|text}.
You can also put references in backticks, like `\`stdvars\``. This is commonly used in You can also put references in backticks, like `\`stdvars\``. This is commonly used in
Markdown to indicate code, so it comes naturally when writing documents. It is controlled by Markdown to indicate code, so it comes naturally when writing documents. It is controlled by
@ -311,20 +316,20 @@ online references to the Linux manpages. So in `config.ld` we have:
return name, url return name, url
end) end)
'^(%a+)%((%d)%)$' both matches the pattern and extracts the name and its section. THen it's '^(%a+)%((%d)%)$' both matches the pattern and extracts the name and its section. Then it's
a simple matter of building up the appropriate URL. The function is expected to a simple matter of building up the appropriate URL. The function is expected to
return _link text_ and _link source_ and the patterns are checked before LDoc tries to resolve return _link text_ and _link source_ and the patterns are checked before LDoc tries to resolve
project references. So it is best to make them match as exactly as possible. project references. So it is best to make them match as exactly as possible.
## Sections ## Sections
LDoc supports _explicit_ sections. By default, the sections correspond to the pre-existing LDoc supports _explicit_ sections. By default, the implicit sections correspond to the pre-existing
types in a module: 'Functions', 'Tables' and 'Fields' (There is another default section types in a module: 'Functions', 'Tables' and 'Fields' (There is another default section
'Local Functions' which only appears if LDoc is invoked with the `--all` flag.) But new 'Local Functions' which only appears if LDoc is invoked with the `--all` flag.) But new
sections can be added; the first mechanism is when you define a new type (say 'macro') a new sections can be added; the first mechanism is when you define a new type (say 'macro'). Then a new
section ('Macros') is created to contain these types. There is also a way to declare ad-hoc section ('Macros') is created to contain these types.
sections using the `@section` tag.
There is also a way to declare ad-hoc sections using the `@section` tag.
The need occurs when a module has a lot of functions that need to be put into logical The need occurs when a module has a lot of functions that need to be put into logical
sections. sections.
@ -442,7 +447,7 @@ However, you must either use the `--colon` flag or set `colon=true` in your `con
In this style, types may be used directly if prefixed with '!' or '?' (for type-or-nil) In this style, types may be used directly if prefixed with '!' or '?' (for type-or-nil)
(see `tests/styles/colon.lua`) (see @{colon.lua})
## Adding new Tags ## Adding new Tags
@ -561,7 +566,7 @@ An LDoc feature which is particularly useful for C extensions is _module merging
files are all marked as `@module lib` then a single module `lib` is generated, containing all files are all marked as `@module lib` then a single module `lib` is generated, containing all
the docs from the separate files. For this, use `merge=true`. the docs from the separate files. For this, use `merge=true`.
See 'tests/examples/mylib.c' for the full example. See @{mylib.c} for the full example.
## Basic Usage ## Basic Usage
@ -628,10 +633,13 @@ markdown, and with extra features (`luarocks install lunamark`).
You can request the processor you like with `format = 'markdown|discount|lunamark'`, and You can request the processor you like with `format = 'markdown|discount|lunamark'`, and
LDoc will attempt to use it. If it can't find it, it will look for one of the other LDoc will attempt to use it. If it can't find it, it will look for one of the other
markdown processors. markdown processors; the original `markdown.lua` ships with LDoc, although it's slow
for larger documents.
Even with the default of 'plain' some minimal processing takes place, in particular empty lines Even with the default of 'plain' some minimal processing takes place, in particular empty lines
are treated as line breaks. are treated as line breaks. If 'process_backticks=true` then backticks will be
expanded into documentation links like `@{\ref}` and converted into `<code>ref</code>`
otherwise.
This formatting applies to all of a project, including any readmes and so forth. You may want This formatting applies to all of a project, including any readmes and so forth. You may want
Markdown for this 'narrative' documentation, but not for your code comments. `plain=true` will Markdown for this 'narrative' documentation, but not for your code comments. `plain=true` will
@ -843,7 +851,7 @@ which is meant to be called from one of the examples. Now a see-reference to `te
resolves to 'examples/testu.lua.html'. resolves to 'examples/testu.lua.html'.
Examples may link back to the API documentation, for instance the example `input.lua` has a Examples may link back to the API documentation, for instance the example `input.lua` has a
@\{spawn_process} inline reference. `@{\spawn_process}` inline reference.
By default, LDoc uses a built-in Lua code 'prettifier'. See-references are allowed in comments, By default, LDoc uses a built-in Lua code 'prettifier'. See-references are allowed in comments,
and also in code if they're enclosed in backticks. and also in code if they're enclosed in backticks.
@ -861,10 +869,10 @@ Like all good Github projects, Winapi has a `readme.md`:
This goes under the 'Topics' global section; the 'Contents' of this document is generated This goes under the 'Topics' global section; the 'Contents' of this document is generated
from the second-level (##) headings of the readme. from the second-level (##) headings of the readme.
Readme files are always processed with the current Markdown processor, but may also contain @\{} references back Readme files are always processed with the current Markdown processor, but may also contain `@{\ref}` references back
to the documentation and to example files. Any symbols within backticks will be expanded as to the documentation and to example files. Any symbols within backticks will be expanded as
references, if possible. As with doc comments, a link to a standard Lua function like references, if possible. As with doc comments, a link to a standard Lua function like
@\{os.execute} will work as well. Any code sections will be pretty-printed as Lua, unless `@{\os.execute}` will work as well. Any code sections will be pretty-printed as Lua, unless
the first indented line is '@plain'. (See the source for this readme to see how it's used.) the first indented line is '@plain'. (See the source for this readme to see how it's used.)
Another name for `readme` is `topics`, which is more descriptive. From LDoc 1.2, Another name for `readme` is `topics`, which is more descriptive. From LDoc 1.2,
@ -878,15 +886,15 @@ second-level, then third-level headings will be used `###`, and so forth. The im
that the first heading must be top-level relative to the headings that follow, and must that the first heading must be top-level relative to the headings that follow, and must
start at the first line. start at the first line.
A reference like @\{string.upper} is unambiguous, and will refer to the online Lua manual. A reference like `@{\string.upper}` is unambiguous, and will refer to the online Lua manual.
In a project like Penlight, it can get tedious to have to write out fully qualified names In a project like Penlight, it can get tedious to have to write out fully qualified names
like @\{pl.utils.printf}. The first simplification is to use the `package` field to resolve like `@{\pl.utils.printf}`. The first simplification is to use the `package` field to resolve
unknown references, which in this case is 'pl'. (Previously we discussed how `package` is unknown references, which in this case is 'pl'. (Previously we discussed how `package` is
used to tell LDoc where the base package is in cases where the module author wishes to used to tell LDoc where the base package is in cases where the module author wishes to
remain vague, but it does double-duty here.) A further level of simplification comes from remain vague, but it does double-duty here.) A further level of simplification comes from
the @lookup directive in documents, which must start at the first column on its own line. the `@lookup` directive in documents, which must start at the first column on its own line.
For instance, if I am talking about `pl.utils`, then I can say "@lookup utils" and For instance, if I am talking about `pl.utils`, then I can say `@lookup utils` and
thereafter references like @\{printf} will resolve correctly. thereafter references like `@{\printf}` will resolve correctly.
If you look at the source for this document, you will see a `@lookup doc.md` which allows If you look at the source for this document, you will see a `@lookup doc.md` which allows
direct references to sections like @{Readme_files|this}. direct references to sections like @{Readme_files|this}.
@ -895,16 +903,16 @@ Remember that the default is for references in backticks to be resolved; unlike
references, it is not an error if the reference cannot be found. references, it is not an error if the reference cannot be found.
The _sections_ of a document (the second-level headings) are also references. This The _sections_ of a document (the second-level headings) are also references. This
particular section can be refered to as @\{doc.md.Resolving_References_in_Documents} - the particular section can be refered to as `@{\doc.md.Resolving_References_in_Documents}` - the
rule is that any non-alphabetic character is replaced by an underscore. rule is that any non-alphabetic character is replaced by an underscore.
## Tag Modifiers ## Tag Modifiers
Ay tag may have _tag modifiers_. For instance, you may say Ay tag may have _tag modifiers_. For instance, you may say
@\param[type=number] and this associates the modifier `type` with value `number` with this `@param[type=number]` and this associates the modifier `type` with value `number` with this
particular param tag. A shorthand can be introduced for this common case, which is "@tparam particular param tag. A shorthand can be introduced for this common case, which is `@tparam
<type> <parmname> <comment>"; in the same way @\treturn is defined. <type> <parmname> <comment>`; in the same way `@treturn` is defined.
This is useful for larger projects where you want to provide the argument and return value This is useful for larger projects where you want to provide the argument and return value
types for your API, in a structured way that can be easily extracted later. There is a types for your API, in a structured way that can be easily extracted later. There is a
@ -973,11 +981,11 @@ then LDoc can present this as the default value for this optional argument.
end end
----> displayed as: one (name, age [, calender='gregorian' [, offset=0]]) ----> displayed as: one (name, age [, calender='gregorian' [, offset=0]])
(See `tests/styles/four.lua`) (See @{four.lua})
## Fields allowed in `config.ld` ## Fields allowed in `config.ld`
These mostly have the same meaning as the corresponding parameters: _Same meaning as the corresponding parameters:_
- `file` a file or directory containing sources. In `config.ld` this can also be a table - `file` a file or directory containing sources. In `config.ld` this can also be a table
of files and directories. of files and directories.
@ -996,17 +1004,20 @@ of files and directories.
template. In `config.ld` they may also be `true`, meaning use the same directory as the template. In `config.ld` they may also be `true`, meaning use the same directory as the
configuration file. configuration file.
- `merge` allow documentation from different files to be merged into modules without - `merge` allow documentation from different files to be merged into modules without
explicit @submodule tag explicit @submodule tag
These only appear in `config.ld`: _These only appear in `config.ld`:_
- `description` a project description used under the project title - `description` a short project description used under the project title
- `full_description` when you _really_ need a longer project description
- `examples` a directory or file: can be a table - `examples` a directory or file: can be a table
- `readme` or `topics` readme files (to be processed with Markdown) - `readme` or `topics` readme files (to be processed with Markdown)
- `pretty` code prettify 'lua' (default) or 'lxsh' - `pretty` code prettify 'lua' (default) or 'lxsh'
- `charset` use if you want to override the UTF-8 default (also @charset in files) - `charset` use if you want to override the UTF-8 default (also @charset in files)
- `sort` set if you want all items in alphabetical order
- `no_return_or_parms` don't show parameters or return values in output - `no_return_or_parms` don't show parameters or return values in output
- `backtick_references` whether references in backticks will be resolved - `backtick_references` whether references in backticks will be resolved. Happens by default
when using Markdown. When explicit will expand non-references in backticks into `<code>` elements
- `plain` set to true if `format` is set but you don't want code comments processed - `plain` set to true if `format` is set but you don't want code comments processed
- `wrap` ?? - `wrap` ??
- `manual_url` point to an alternative or local location for the Lua manual, e.g. - `manual_url` point to an alternative or local location for the Lua manual, e.g.
@ -1014,8 +1025,10 @@ These only appear in `config.ld`:
- `no_summary` suppress the Contents summary - `no_summary` suppress the Contents summary
- `custom_see_handler` function that filters see-references - `custom_see_handler` function that filters see-references
- `not_luadoc` set to `true` if the docs break LuaDoc compatibility - `not_luadoc` set to `true` if the docs break LuaDoc compatibility
- `no_space_before_args` set to `true` if you do not want a space between a function's name and its arguments.
- `template_escape` overrides the usual '#' used for Lua code in templates. This needs to be changed if the output format is Markdown, for instance.
Available functions are: _Available functions are:_
- `alias(a,tag)` provide an alias `a` for the tag `tag`, for instance `p` as short for - `alias(a,tag)` provide an alias `a` for the tag `tag`, for instance `p` as short for
`param` `param`
@ -1024,8 +1037,8 @@ an extension to be recognized as this language
- `add_section` - `add_section`
- `new_type(tag,header,project_level)` used to add new tags, which are put in their own - `new_type(tag,header,project_level)` used to add new tags, which are put in their own
section `header`. They may be 'project level'. section `header`. They may be 'project level'.
- `tparam_alias(name,type)` for instance, you may wish that `Object` means `@\tparam - `tparam_alias(name,type)` for instance, you may wish that `Object` becomes a new tag alias
Object`. that means `@tparam Object`.
- `custom_see_handler(pattern,handler)`. If a reference matches `pattern`, then the - `custom_see_handler(pattern,handler)`. If a reference matches `pattern`, then the
extracted values will be passed to `handler`. It is expected to return link text extracted values will be passed to `handler`. It is expected to return link text
and a suitable URI. (This match will happen before default processing.) and a suitable URI. (This match will happen before default processing.)
@ -1059,9 +1072,10 @@ Although not currently rendered by the template as HTML, they can be extracted b
## Generating HTML ## Generating HTML
LDoc, like LuaDoc, generates output HTML using a template, in this case `ldoc_ltp.lua`. This LDoc, like LuaDoc, generates output HTML using a template, in this case `ldoc/html/ldoc_ltp.lua`. This
is expanded by the powerful but simple preprocessor devised originally by [Rici is expanded by the powerful but simple preprocessor devised originally by [Rici
Lake](http://lua-users.org/wiki/SlightlyLessSimpleLuaPreprocessor) which is now part of Lake](http://lua-users.org/wiki/SlightlyLessSimpleLuaPreprocessor) which is now part of
Lake](http://lua-users.org/wiki/SlightlyLessSimpleLuaPreprocessor) which is now part of
Penlight. There are two rules - any line starting with '#' is Lua code, which can also be Penlight. There are two rules - any line starting with '#' is Lua code, which can also be
embedded with '$(...)'. embedded with '$(...)'.
@ -1093,6 +1107,10 @@ extension to use; this can also be set in the configuration file. So it's possib
a template that converts LDoc output to LaTex, for instance. The separation of processing a template that converts LDoc output to LaTex, for instance. The separation of processing
and presentation makes this kind of new application possible with LDoc. and presentation makes this kind of new application possible with LDoc.
From 1.4, LDoc has some limited support for generating Markdown output, although only
for single files currently. Use `--ext md` for this. 'ldoc/html/ldoc_mdtp.lua' defines
the template for Markdown.
## Internal Data Representation ## Internal Data Representation
The `--dump` flag gives a rough text output on the console. But there is a more The `--dump` flag gives a rough text output on the console. But there is a more

2
ldoc.lua
View File

@ -35,7 +35,7 @@ app.require_here()
--- @usage --- @usage
local usage = [[ local usage = [[
ldoc, a documentation generator for Lua, vs 1.3.12 ldoc, a documentation generator for Lua, vs 1.4.0
-d,--dir (default doc) output directory -d,--dir (default doc) output directory
-o,--output (default 'index') output name -o,--output (default 'index') output name
-v,--verbose verbose -v,--verbose verbose

2
ldoc/doc.lua
View File

@ -122,7 +122,7 @@ function doc.module_info_tags ()
end end
-- annotation tags can appear anywhere in the code and may contain of these tags: -- annotation tags can appear anywhere in the code and may contain any of these tags:
known_tags._annotation_tags = { known_tags._annotation_tags = {
fixme = true, todo = true, warning = true fixme = true, todo = true, warning = true
} }

2
ldoc/html/ldoc_ltp.lua
View File

@ -254,7 +254,7 @@ return [==[
</div> <!-- id="content" --> </div> <!-- id="content" -->
</div> <!-- id="main" --> </div> <!-- id="main" -->
<div id="about"> <div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.3.12</a></i> <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.0</a></i>
</div> <!-- id="about" --> </div> <!-- id="about" -->
</div> <!-- id="container" --> </div> <!-- id="container" -->
</body> </body>

1
ldoc/markup.lua
View File

@ -15,6 +15,7 @@ local backtick_references
-- inline <references> use same lookup as @see -- inline <references> use same lookup as @see
local function resolve_inline_references (ldoc, txt, item, plain) local function resolve_inline_references (ldoc, txt, item, plain)
local res = (txt:gsub('@{([^}]-)}',function (name) local res = (txt:gsub('@{([^}]-)}',function (name)
if name:match '^\\' then return '@{'..name:sub(2)..'}' end
local qname,label = utils.splitv(name,'%s*|') local qname,label = utils.splitv(name,'%s*|')
if not qname then if not qname then
qname = name qname = name