Update documentation links

https://github.com/lunarmodules/LDoc/issues/354
This commit is contained in:
Pierre Chapuis 2021-06-24 13:07:51 +02:00
parent 147951025b
commit bbd498ab39
2 changed files with 22 additions and 23 deletions

View File

@ -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`.

View File

@ -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.