Update documentation links
https://github.com/lunarmodules/LDoc/issues/354
This commit is contained in:
parent
147951025b
commit
bbd498ab39
|
@ -10,10 +10,10 @@ This project grew out of the documentation needs of
|
||||||
[Penlight](https://github.com/lunarmodules/Penlight) (and not always getting satisfaction
|
[Penlight](https://github.com/lunarmodules/Penlight) (and not always getting satisfaction
|
||||||
with LuaDoc) and depends on Penlight itself. (This allowed me to _not_ write a lot of code.)
|
with LuaDoc) and depends on Penlight itself. (This allowed me to _not_ write a lot of code.)
|
||||||
|
|
||||||
The [API documentation](http://lunarmodules.github.com/Penlight/api/index.html) of Penlight
|
The [API documentation](https://lunarmodules.github.io/Penlight/) of Penlight
|
||||||
is an example of a project using plain LuaDoc markup processed using LDoc.
|
is an example of a project using plain LuaDoc markup processed using LDoc.
|
||||||
|
|
||||||
LDoc is intended to be compatible with [LuaDoc](http://keplerproject.github.io/luadoc/) and
|
LDoc is intended to be compatible with [LuaDoc](https://keplerproject.github.io/luadoc/) and
|
||||||
thus follows the pattern set by the various *Doc tools:
|
thus follows the pattern set by the various *Doc tools:
|
||||||
|
|
||||||
--- Summary ends with a period.
|
--- Summary ends with a period.
|
||||||
|
@ -36,14 +36,14 @@ having to embed HTML in commments by using Markdown.
|
||||||
LDoc will also work with Lua C extension code, and provides some convenient shortcuts.
|
LDoc will also work with Lua C extension code, and provides some convenient shortcuts.
|
||||||
|
|
||||||
An example showing the support for named sections and 'classes' is the [Winapi
|
An example showing the support for named sections and 'classes' is the [Winapi
|
||||||
documentation](http://stevedonovan.github.com/winapi/api.html); this is generated from
|
documentation](https://stevedonovan.github.io/winapi/api.html); this is generated from
|
||||||
[winapi.l.c](https://github.com/stevedonovan/winapi/blob/master/winapi.l.c).
|
[winapi.l.c](https://github.com/stevedonovan/winapi/blob/master/winapi.l.c).
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
This is straightforward; the only external dependency is
|
This is straightforward; the only external dependency is
|
||||||
[Penlight](https://github.com/lunarmodules/Penlight), which in turn needs
|
[Penlight](https://github.com/lunarmodules/Penlight), which in turn needs
|
||||||
[LuaFileSystem](http://keplerproject.github.com/luafilesystem/). These are already present
|
[LuaFileSystem](https://keplerproject.github.io/luafilesystem/). These are already present
|
||||||
in [Lua for Windows](https://github.com/rjpcomputing/luaforwindows), and Penlight is also available through [LuaRocks](https://luarocks.org/) as `luarocks install
|
in [Lua for Windows](https://github.com/rjpcomputing/luaforwindows), and Penlight is also available through [LuaRocks](https://luarocks.org/) as `luarocks install
|
||||||
penlight`.
|
penlight`.
|
||||||
|
|
||||||
|
|
37
doc/doc.md
37
doc/doc.md
|
@ -9,7 +9,7 @@ out of source code comments (doc comments). It is mainly targeted at Lua and doc
|
||||||
Lua APIs, but it can also parse C with according doc comments for documenting Lua modules
|
Lua APIs, but it can also parse C with according doc comments for documenting Lua modules
|
||||||
implemented in C.
|
implemented in C.
|
||||||
|
|
||||||
It is mostly compatible with [LuaDoc](http://keplerproject.github.com/luadoc/),
|
It is mostly compatible with [LuaDoc](http://keplerproject.github.io/luadoc/),
|
||||||
except that certain workarounds are no longer needed.
|
except that certain workarounds are no longer needed.
|
||||||
For instance, it is not so married to the idea that Lua modules should be defined using the
|
For instance, it is not so married to the idea that Lua modules should be defined using the
|
||||||
`module` function; this is not only a matter of taste since this has been deprecated in Lua
|
`module` function; this is not only a matter of taste since this has been deprecated in Lua
|
||||||
|
@ -17,7 +17,7 @@ For instance, it is not so married to the idea that Lua modules should be define
|
||||||
|
|
||||||
Otherwise, the output is very similar, which is no accident since the HTML templates are
|
Otherwise, the output is very similar, which is no accident since the HTML templates are
|
||||||
based directly on LuaDoc. You can ship your own customized templates and style sheets with
|
based directly on LuaDoc. You can ship your own customized templates and style sheets with
|
||||||
your [own project](http://nilnor.github.com/textui/docs/) (also see Graham Hannington's
|
your [own project](https://nilnor.github.io/textui/docs/) (also see Graham Hannington's
|
||||||
documentation for [Lua for z/OS](http://lua4z.com/doc/)). LDoc comes with three extra themes; 'pale'
|
documentation for [Lua for z/OS](http://lua4z.com/doc/)). LDoc comes with three extra themes; 'pale'
|
||||||
for those who like whitespace, 'one' for one-column output, and 'fixed' for a fixed navigation
|
for those who like whitespace, 'one' for one-column output, and 'fixed' for a fixed navigation
|
||||||
bar down the left side.
|
bar down the left side.
|
||||||
|
@ -327,7 +327,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 @{colon.lua}, rendered [here](http://stevedonovan.github.io/ldoc/examples/colon))
|
(see @{colon.lua})
|
||||||
|
|
||||||
## Sections
|
## Sections
|
||||||
|
|
||||||
|
@ -362,7 +362,7 @@ the new section title, and the description will be output at the start of the fu
|
||||||
details for that section; the name is not used, but must be unique.
|
details for that section; the name is not used, but must be unique.
|
||||||
|
|
||||||
Sections appear under 'Contents' on the left-hand side. See the
|
Sections appear under 'Contents' on the left-hand side. See the
|
||||||
[winapi](http://stevedonovan.github.com/winapi/api.html) documentation for an example of how
|
[winapi](https://stevedonovan.github.io/winapi/api.html) documentation for an example of how
|
||||||
this looks.
|
this looks.
|
||||||
|
|
||||||
Arguably a module writer should not write such very long modules, but it is not the job of
|
Arguably a module writer should not write such very long modules, but it is not the job of
|
||||||
|
@ -687,7 +687,7 @@ See @{mylib.c} for the full example.
|
||||||
|
|
||||||
## Moonscript Support
|
## Moonscript Support
|
||||||
|
|
||||||
1.4 introduces basic support for [Moonscript](http://moonscript.org). Moonscript module
|
1.4 introduces basic support for [Moonscript](https://moonscript.org). Moonscript module
|
||||||
conventions are just the same as Lua, except for an explicit class construct.
|
conventions are just the same as Lua, except for an explicit class construct.
|
||||||
@{List.moon} shows how **@classmod** can declare modules that export one class, with metamethods
|
@{List.moon} shows how **@classmod** can declare modules that export one class, with metamethods
|
||||||
and methods put implicitly into a separate section.
|
and methods put implicitly into a separate section.
|
||||||
|
@ -746,13 +746,13 @@ line. This is useful if you have some defaults you wish to apply to all of your
|
||||||
and descriptions; you can also use the `-f` flag. This requires a markdown processor.
|
and descriptions; you can also use the `-f` flag. This requires a markdown processor.
|
||||||
LDoc knows how to use:
|
LDoc knows how to use:
|
||||||
|
|
||||||
- [markdown.lua](http://www.frykholm.se/files/markdown.lua) a pure Lua processor by
|
- [markdown.lua](https://www.frykholm.se/files/markdown.lua) a pure Lua processor by
|
||||||
Niklas Frykholm. For convenience, LDoc comes with a copy of markdown.lua.
|
Niklas Frykholm. For convenience, LDoc comes with a copy of markdown.lua.
|
||||||
- [lua-discount](http://asbradbury.org/projects/lua-discount/), a faster alternative
|
- [lua-discount](http://asbradbury.org/projects/lua-discount/), a faster alternative
|
||||||
(installed with `luarocks install lua-discount`). lua-discount uses the C
|
(installed with `luarocks install lua-discount`). lua-discount uses the C
|
||||||
[discount](http://www.pell.portland.or.us/~orc/Code/discount/) Markdown processor which has
|
[discount](https://www.pell.portland.or.us/~orc/Code/discount/) Markdown processor which has
|
||||||
more features than the pure Lua version, such as PHP-Extra style tables.
|
more features than the pure Lua version, such as PHP-Extra style tables.
|
||||||
- [lunamark](http://jgm.github.com/lunamark/), another pure Lua processor, faster than
|
- [lunamark](https://jgm.github.io/lunamark/), another pure Lua processor, faster than
|
||||||
markdown, and with extra features (`luarocks install lunamark`).
|
markdown, and with extra features (`luarocks install lunamark`).
|
||||||
- commonmark via [cmark-lua](https://github.com/jgm/cmark-lua), a Lua wrapper
|
- commonmark via [cmark-lua](https://github.com/jgm/cmark-lua), a Lua wrapper
|
||||||
around the fast [libcmark](https://github.com/jgm/cmark) C library (`luarocks
|
around the fast [libcmark](https://github.com/jgm/cmark) C library (`luarocks
|
||||||
|
@ -854,9 +854,9 @@ LDoc knows about the basic Lua libraries, so that it can be used as a handy cons
|
||||||
v
|
v
|
||||||
message
|
message
|
||||||
|
|
||||||
Thanks to Mitchell's [Textadept](http://foicica.com/textadept/) project, LDoc has a
|
Thanks to Mitchell's [Textadept](https://orbitalquark.github.io/textadept/) project, LDoc has a
|
||||||
set of `.luadoc` files for all the standard tables, plus
|
set of `.luadoc` files for all the standard tables, plus
|
||||||
[LuaFileSystem](http://keplerproject.github.com/luafilesystem/) and
|
[LuaFileSystem](https://keplerproject.github.io/luafilesystem/) and
|
||||||
[LPeg](http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html).
|
[LPeg](http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html).
|
||||||
|
|
||||||
@plain
|
@plain
|
||||||
|
@ -878,7 +878,7 @@ set of `.luadoc` files for all the standard tables, plus
|
||||||
|
|
||||||
## Anatomy of a LDoc-generated Page
|
## Anatomy of a LDoc-generated Page
|
||||||
|
|
||||||
[winapi](http://stevedonovan.github.com/winapi/api.html) can be used as a good example of a
|
[winapi](https://stevedonovan.github.io/winapi/api.html) can be used as a good example of a
|
||||||
module that uses extended LDoc features.
|
module that uses extended LDoc features.
|
||||||
|
|
||||||
The _navigation section_ down the left has several parts:
|
The _navigation section_ down the left has several parts:
|
||||||
|
@ -898,9 +898,9 @@ the subtitles become the sections shown here.
|
||||||
|
|
||||||
**Modules** will appear for any project providing Lua libraries; there may also be a 'Scripts'
|
**Modules** will appear for any project providing Lua libraries; there may also be a 'Scripts'
|
||||||
section if the project contains Lua scripts. For example,
|
section if the project contains Lua scripts. For example,
|
||||||
[LuaMacro](http://stevedonovan.github.com/LuaMacro/docs/api.html) has a driver script `luam`
|
[LuaMacro](https://stevedonovan.github.io/LuaMacro/docs/api.html) has a driver script `luam`
|
||||||
in this section. The
|
in this section. The
|
||||||
[builtin](http://stevedonovan.github.com/LuaMacro/docs/modules/macro.builtin.html) module
|
[builtin](https://stevedonovan.github.io/LuaMacro/docs/modules/macro.builtin.html) module
|
||||||
only defines macros, which are defined as a _custom tag type[?]_.
|
only defines macros, which are defined as a _custom tag type[?]_.
|
||||||
|
|
||||||
The _content section_ on the right shows:
|
The _content section_ on the right shows:
|
||||||
|
@ -946,7 +946,7 @@ Markdown in a stylized way to specify arguments:
|
||||||
Here I've chosen to italicise parameter names; the main thing is to be consistent.
|
Here I've chosen to italicise parameter names; the main thing is to be consistent.
|
||||||
|
|
||||||
This style is close to the Python [documentation
|
This style is close to the Python [documentation
|
||||||
standard](http://docs.python.org/library/array.html#module-array), especially when used with
|
standard](https://docs.python.org/library/array.html#module-array), especially when used with
|
||||||
`no_summary`.
|
`no_summary`.
|
||||||
|
|
||||||
It is also very much how the Lua documentation is ordered. For instance, this configuration
|
It is also very much how the Lua documentation is ordered. For instance, this configuration
|
||||||
|
@ -962,7 +962,7 @@ to the original:
|
||||||
|
|
||||||
Generally, using Markdown gives you the opportunity to structure your documentation in any
|
Generally, using Markdown gives you the opportunity to structure your documentation in any
|
||||||
way you want; particularly if using lua-discount and its [table
|
way you want; particularly if using lua-discount and its [table
|
||||||
syntax](http://michelf.com/projects/php-markdown/extra/#table); the desired result can often
|
syntax](https://michelf.com/projects/php-markdown/extra/#table); the desired result can often
|
||||||
be achieved then by using a custom style sheet.
|
be achieved then by using a custom style sheet.
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
|
@ -973,7 +973,7 @@ and they like looking at examples. Previously I found myself dealing with sourc
|
||||||
and writer-generated documentation using different tools, and having to match these up.
|
and writer-generated documentation using different tools, and having to match these up.
|
||||||
|
|
||||||
LDoc allows for source examples to be included in the documentation. For example, see the
|
LDoc allows for source examples to be included in the documentation. For example, see the
|
||||||
online documentation for [winapi](http://stevedonovan.github.com/winapi/api.html). The
|
online documentation for [winapi](https://stevedonovan.github.io/winapi/api.html). The
|
||||||
function `utf8_expand` has a **@see** reference to 'testu.lua' and following that link gives
|
function `utf8_expand` has a **@see** reference to 'testu.lua' and following that link gives
|
||||||
you a pretty-printed version of the code.
|
you a pretty-printed version of the code.
|
||||||
|
|
||||||
|
@ -1146,7 +1146,7 @@ This modifier can also be used with typed param aliases.
|
||||||
end
|
end
|
||||||
----> displayed as: one (name, age [, calender='gregorian' [, offset=0]])
|
----> displayed as: one (name, age [, calender='gregorian' [, offset=0]])
|
||||||
|
|
||||||
(See @{four.lua}, rendered [here](http://stevedonovan.github.io/ldoc/examples/four))
|
(See @{four.lua})
|
||||||
|
|
||||||
An experimental feature in 1.4 allows different 'return groups' to be defined. There may be
|
An experimental feature in 1.4 allows different 'return groups' to be defined. There may be
|
||||||
multiple **@return** tags, and the meaning of this is well-defined, since Lua functions may
|
multiple **@return** tags, and the meaning of this is well-defined, since Lua functions may
|
||||||
|
@ -1166,8 +1166,7 @@ as a group:
|
||||||
-- @return[2] error message
|
-- @return[2] error message
|
||||||
function mul1() ... end
|
function mul1() ... end
|
||||||
|
|
||||||
This is the first function in @{multiple.lua}, and the [output](http://stevedonovan.github.io/ldoc/examples/multiple)
|
This is the first function in @{multiple.lua}, and the output shows how return groups are presented, with an **Or** between the groups.
|
||||||
shows how return groups are presented, with an **Or** between the groups.
|
|
||||||
|
|
||||||
This is rather clumsy, and so there is a shortcut, the **@error** tag which achieves the same result,
|
This is rather clumsy, and so there is a shortcut, the **@error** tag which achieves the same result,
|
||||||
with helpful type information.
|
with helpful type information.
|
||||||
|
|
Loading…
Reference in New Issue