From 1bf3461917a545727b0111e4cea99089ebfb12c4 Mon Sep 17 00:00:00 2001 From: Steve Donovan Date: Fri, 23 Aug 2013 15:59:35 +0200 Subject: [PATCH] doc updates --- doc/doc.md | 48 ++++++++++++++++++++++++------------------ tests/styles/colon.lua | 11 ++++++++-- tests/styles/four.lua | 2 +- 3 files changed, 38 insertions(+), 23 deletions(-) diff --git a/doc/doc.md b/doc/doc.md index 98bfc13..29b7b0f 100644 --- a/doc/doc.md +++ b/doc/doc.md @@ -225,7 +225,7 @@ If you want to document scripts, then use `@script` instead of `@module`. New wi ## See References The tag 'see' is used to reference other parts of the documentation, and 'usage' can provide -examples of use: +examples of use; there can be multiple such tags: --------- -- split a string in two. @@ -897,7 +897,7 @@ For instance, if I am talking about `pl.utils`, then I can say `@lookup utils` a 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 -direct references to sections like @{Readme_files|this}. +direct references to sections like @{Readme_files|this} with `@{\Readme_files|this}`. 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. @@ -906,21 +906,26 @@ The _sections_ of a document (the second-level headings) are also references. Th 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. - ## Tag Modifiers 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 -particular param tag. A shorthand can be introduced for this common case, which is `@tparam +particular param tag. A shorthand has been introduced for this common case, which is `@tparam `; in the same way `@treturn` is defined. 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 -useful function for creating new tags that can be used in `config.ld`: +types for your API, in a structured way that can be easily extracted later. + +These types can be combined, so that "?string|number" means "ether a string or a number"; +"?string" is short for "?|nil|string". However, for this last case you should usually use the +`opt` modifier discussed below. + +There is a useful function for creating new tags that can be used in `config.ld`: tparam_alias('string','string') -That is, "@string" will now have the same meaning as "@tparam string". +That is, "@string" will now have the same meaning as "@tparam string"; this also applies +to the optional type syntax "?|T1|T2". From 1.3, the following standard type aliases are predefined: @@ -932,19 +937,18 @@ From 1.3, the following standard type aliases are predefined: * `tab` 'table' * `thread` -The exact form of `` is not defined, but here is a suggested scheme: +When using 'colon-style' (@{colon.lua}) it's possible to directly use types by prepending +them with '!'; '?' is also naturally understood. - number -- a plain type - Bonzo -- a known type; a reference link will be generated - {string,number} -- a 'list' tuple, built from type expressions - {A=string,N=number} -- a 'struct' tuple, ditto - {Bonzo,...} -- an array of Bonzo objects - {[string]=Bonzo,...} -- a map of Bonzo objects with string keys - Array(Bonzo) -- (assuming that Array is a container) +The exact form of `` is not defined, but here is one suggested scheme: -Currently the `type` modifier is the only one known and used by LDoc when generating HTML -output. However, any other modifiers are allowed and are available for use with your own -templates or for extraction by your own tools. + * `number` -- a plain type + * `Bonzo` -- a known type; a reference link will be generated + * `{string,number}` -- a 'list' tuple of two values, built from type expressions + * `{A=string,N=number}` -- a 'struct', ditto (But it's often better to create a named table and refer to it) + * `{Bonzo,...}` -- an array of Bonzo objects + * `{[string]=Bonzo,...}` -- a map of Bonzo objects with string keys + * `Array(Bonzo)` -- (assuming that Array is a container type) The `alias` function within configuration files has been extended so that alias tags can be defined as a tag plus a set of modifiers. So `tparam` is defined as: @@ -966,7 +970,7 @@ Another modifier understood by LDoc is `opt`. For instance, end ----> displayed as: two (one [, two], three [, four]) -This modifier can also be used with type aliases. If a value is given for the modifier +This modifier can also be used with type aliases. If a value is given for `opt` then LDoc can present this as the default value for this optional argument. --- a function with typed args. @@ -981,6 +985,10 @@ then LDoc can present this as the default value for this optional argument. end ----> displayed as: one (name, age [, calender='gregorian' [, offset=0]]) +Currently the `type` and `opt` modifiers are the only ones known and used by LDoc when generating HTML +output. However, any other modifiers are allowed and are available for use with your own +templates or for extraction by your own tools. + (See @{four.lua}) ## Fields allowed in `config.ld` @@ -1006,7 +1014,7 @@ configuration file. - `merge` allow documentation from different files to be merged into modules without explicit @submodule tag -_These only appear in `config.ld`:_ +_These only appear in config.ld:_ - `description` a short project description used under the project title - `full_description` when you _really_ need a longer project description diff --git a/tests/styles/colon.lua b/tests/styles/colon.lua index ea72ead..1791257 100644 --- a/tests/styles/colon.lua +++ b/tests/styles/colon.lua @@ -11,15 +11,22 @@ --- first useless function. -- Optional type specifiers are allowed in this format. --- As an extension, '?' is short for '?|'. +-- As an extension, '?T' is short for '?nil|T'. -- Note how these types are rendered! -- string: name -- int: age --- ?person2: options +-- ?person3: options -- treturn: ?table|string function one (name,age,options) end +--- implicit table can always use colon notation. +person2 = { + id=true, -- string: official ID number + sex=true, -- string: one of 'M', 'F' or 'N' + spouse=true, -- ?person3: wife or husband +} + --- explicit table in colon format. -- Note how '!' lets you use a type name directly. -- string: surname diff --git a/tests/styles/four.lua b/tests/styles/four.lua index a178726..4c3f290 100644 --- a/tests/styles/four.lua +++ b/tests/styles/four.lua @@ -11,7 +11,7 @@ -- Note the the standard tparam aliases, and how the 'opt' and 'optchain' -- modifiers may also be used. If the Lua function has varargs, then -- you may document an indefinite number of extra arguments! --- @string name person's name +-- @tparam ?string|Person name person's name -- @int age -- @string[opt='gregorian'] calender optional calendar -- @int[opt=0] offset optional offset