From 2fbe566039ff60d9050a6e578f9caa174246a4c2 Mon Sep 17 00:00:00 2001 From: steve donovan Date: Tue, 21 Oct 2014 17:57:26 +0200 Subject: [PATCH] Bumped version to 1.4.3; doc updates; C lexer ignores strings (which it handles badly) --- changes.md | 134 ++++++++++++++++++++++++----------------- doc/doc.md | 66 ++++++++++++++------ ldoc/html/ldoc_ltp.lua | 2 +- ldoc/lexer.lua | 6 +- 4 files changed, 129 insertions(+), 79 deletions(-) diff --git a/changes.md b/changes.md index b6e06f8..3383bcf 100644 --- a/changes.md +++ b/changes.md @@ -1,56 +1,78 @@ -## Version 1.4.2 - -### Features - - * Can define fields/properties of objects; `readonly` modifier supported (#93) - * Can switch off auto-linking to Lua manual with `no_lua_ref` - * Module sorting is off by default, use `sort_modules=true` - * References to 'classes' now work properly - * Option to use first Markdown title instead of file names with `use_markdown_titles` - * Automatic `Metamethods` and `Methods` sections generated for `classmod` classes - * `unqualified=true` to strip package names on sidebar (#110) - * Custom tags (which may be hidden) - * Custom Display Name handlers - -### Fixes - - * stricter about doc comments, now excludes common '----- XXXXX ----' pattern - * no longer expects space after `##` in Markdown (#96) - * Section lookup was broken - * With `export` tag, decide whether method is static or not - * `classmod` classes now respect custom sections (#113) - * Minor issues with prettification - * Command-line flags set explicitly take precendence over configuration file values. - * Boilerplate Lua block comment ignored properly (#137) - * Inline links with underscores sorted (#22) - * Info section ordering is now consistent (#150) - -## Version 1.4.0 - -### Features - - * `sort=true` to sort items within sections alphabetically - * `@set` tag in module comments; e.g, can say `@set sort=true` - * `@classmod` tag for defining modules that export one class - * can generate Markdown output - * Can prettify C as well as Lua code with built-in prettifier - * lfs and lpeg references understood - * 'pale' template available - * multiple return groups - * experimental `@error` tag - * Moonscript and plain C support - - -### Fixes - - * works with non-compatibily Lua 5.2, including `markdown.lua` - * module names can not be types - * all `builtin` Lua files are requirable without `module` - * backticks expand in copyright and other 'info' tabs - * `-m` tries harder to resolve methods - * auto-scroll in navigation area to avoid breaking identifiers - * better error message for non-luadoc-compatible behaviour - * custom see references fixed - - - +## Version 1.4.3 + +### Features + + * @include tag for including Markdown documentation file directly into module docstring + * `prettify_files` makes per-item links to prettified source. + * link targets rendered in bright yellow to make referenced functions more obvious + * add update time to footer of page + * better C support: `global_lookup=true` - invoked when `parse_extra={C=true}` + * `kind_names` can override names used in sidebar + +### Fixes + + * `all=true` in `config.ld` did not work. + * `dont_escape_underscore` logic fixed: do not use in prettified code blocks + * check that `ldoc` config exists before checking field values + * annotation rendering fixed + * summary not dropped when using `type` sections + * directory as argument case was broken + * parameter names which were List methods causing mayhem + * files are processed in fixed order across platforms + +## Version 1.4.2 + +### Features + + * Can define fields/properties of objects; `readonly` modifier supported (#93) + * Can switch off auto-linking to Lua manual with `no_lua_ref` + * Module sorting is off by default, use `sort_modules=true` + * References to 'classes' now work properly + * Option to use first Markdown title instead of file names with `use_markdown_titles` + * Automatic `Metamethods` and `Methods` sections generated for `classmod` classes + * `unqualified=true` to strip package names on sidebar (#110) + * Custom tags (which may be hidden) + * Custom Display Name handlers + +### Fixes + + * stricter about doc comments, now excludes common '----- XXXXX ----' pattern + * no longer expects space after `##` in Markdown (#96) + * Section lookup was broken + * With `export` tag, decide whether method is static or not + * `classmod` classes now respect custom sections (#113) + * Minor issues with prettification + * Command-line flags set explicitly take precendence over configuration file values. + * Boilerplate Lua block comment ignored properly (#137) + * Inline links with underscores sorted (#22) + * Info section ordering is now consistent (#150) + +## Version 1.4.0 + +### Features + + * `sort=true` to sort items within sections alphabetically + * `@set` tag in module comments; e.g, can say `@set sort=true` + * `@classmod` tag for defining modules that export one class + * can generate Markdown output + * Can prettify C as well as Lua code with built-in prettifier + * lfs and lpeg references understood + * 'pale' template available + * multiple return groups + * experimental `@error` tag + * Moonscript and plain C support + + +### Fixes + + * works with non-compatibily Lua 5.2, including `markdown.lua` + * module names can not be types + * all `builtin` Lua files are requirable without `module` + * backticks expand in copyright and other 'info' tabs + * `-m` tries harder to resolve methods + * auto-scroll in navigation area to avoid breaking identifiers + * better error message for non-luadoc-compatible behaviour + * custom see references fixed + + + diff --git a/doc/doc.md b/doc/doc.md index 3913ad3..3b5fee4 100644 --- a/doc/doc.md +++ b/doc/doc.md @@ -143,12 +143,14 @@ This is a simple example of a documented function: You can also give the function name itself as an explicit tag, which is especially useful when documenting a Lua api exported by C code: - /// A C function which is exported to Lua with another name, - // because the ways of C can be mysterious! - // @function our_nice_function - int _some_function_for_lua(lua_State* l) { - .... - } +```C +/// A C function which is exported to Lua with another name, +// because the ways of C can be mysterious! +// @function our_nice_function +int _some_function_for_lua(lua_State* l) { + .... +} +``` The tags basically add all the detail that cannot be derived from the source code automatically. @@ -189,7 +191,6 @@ function. For Lua, there can also be multiple 'return' tags end ... -Of course there is also the 'module' tag which you have already seen. #### Tables and constant values (fields) @@ -216,7 +217,8 @@ This can get tedious, so LDoc will attempt to extract table documentation from c The rule followed here is `NAME = `. If LDoc can't work out the name and type from the following code, then a warning will be issued, pointing to the file and -location. +location. Only single-level tables are currently supported, and the fields must be valid +identifiers. Another kind of module-level type is 'field', such as follows: @@ -239,9 +241,8 @@ When the code analysis would lead to the wrong type, you can always be explicit. ... end -As mentioned before, this is often especially useful in C where things -may look different in the C code than they will in the final Lua api which -you want to document. +This is especially useful in C where the function declarations +are different from final Lua api which you are documenting. ### Doing modules the Lua 5.1 way @@ -293,7 +294,8 @@ explicit assignment to a variable: ### Local functions Apart from exported functions, a module usually contains local functions. By default, LDoc -does not include these in the documentation, but they can be enabled using the `--all` flag. +does not include these in the documentation, but they can be enabled using the `--all` flag, +or `all=true` in `config.ld`. They can be documented just like 'public' functions: --- it's clear that boo is local from context. @@ -406,8 +408,12 @@ type of a parameter or return value when that type has a particular structure: 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 -Markdown to indicate code, so it comes naturally when writing documents. It is controlled by -the configuration variable `backtick_references` or the `backtick` format; +Markdown to indicate code, so it comes naturally when writing documents. The difference +is that the backticked expression does not have to be a reference and then will appear +in code style; with @ references you will get a warning for unrecognized symbols +and the result will be rendered as '???'. + +It is controlled by the configuration variable `backtick_references` or the `backtick` format; the default is `true` if you use Markdown in your project, but can be specified explicitly in `config.ld`. @@ -944,6 +950,9 @@ control what the template will generate. Setting `one=true` in your configuratio will give a _one-column_ layout, which can be easier to use as a programming reference. You can suppress the contents summary with `no_summary`. +If you don't like the usual top-level names, like 'Module' and 'Topics', you can override these +with `kind_names` in `config.ld`. For instance, in Penlight I use `kind_names={topic='Manual',module='Libraries'}` + ## Customizing the Page A basic customization is to override the default UTF-8 encoding using `charset`. For instance, @@ -1012,6 +1021,9 @@ and also in code if they're enclosed in backticks. Lua and C are known languages can be used (available from LuaRocks) if you want something more powerful. `pretty='lxsh'` will cause `lxsh` to be used, if available. +Sometimes the best examples you have are your source files. `prettify_files=true` will prettify +all sources, and generate per-function links to the source. + ## Readme files Like all good Github projects, Winapi has a `readme.md`: @@ -1116,6 +1128,7 @@ As an extension, you're allowed to use **@param** tags in table definitions. Thi possible to use type aliases like **@string** to describe fields, since they will expand to 'param'. + Another modifier understood by LDoc is `opt`. For instance, ---- testing [opt] @@ -1123,12 +1136,28 @@ Another modifier understood by LDoc is `opt`. For instance, -- @param[opt] two -- @param three -- @param[opt] four - function two (one,two,three,four) + function fun (one,two,three,four) end - ----> displayed as: two (one [, two], three [, four]) + ----> displayed as: fun (one [, two], three [, four]) + +A more typical Lua API would have a chain of optional arguments, like so: -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 chain of options + -- @param one + -- @param[opt] two + -- @param[optchain] three + -- @param[optchain] four + function fun (one,two,three,four) + end + ----> displayed as: fun (one [, two [, three [, four]]]) + +This is a bit tedious to type, so the rule is that a series of 'opt' modifiers will be interpreted +as 'opt','optchain'.... . If you want to be explicit, then do `convert_opt=true` in your +`config.ld`. + +If a value is given for `opt`then LDoc can present this as the default value for this optional argument. + +This modifier can also be used with typed param aliases. --- a function with typed args. -- If the Lua function has varargs, then @@ -1142,7 +1171,6 @@ then LDoc can present this as the default value for this optional argument. end ----> displayed as: one (name, age [, calender='gregorian' [, offset=0]]) - (See @{four.lua}, rendered [here](http://stevedonovan.github.io/ldoc/examples/four)) An experimental feature in 1.4 allows different 'return groups' to be defined. There may be diff --git a/ldoc/html/ldoc_ltp.lua b/ldoc/html/ldoc_ltp.lua index d83147c..07c8a84 100644 --- a/ldoc/html/ldoc_ltp.lua +++ b/ldoc/html/ldoc_ltp.lua @@ -289,7 +289,7 @@ return [==[
-generated by LDoc 1.4.2 +generated by LDoc 1.4.3 Last updated $(ldoc.updatetime)
diff --git a/ldoc/lexer.lua b/ldoc/lexer.lua index fa50ac8..80d3060 100644 --- a/ldoc/lexer.lua +++ b/ldoc/lexer.lua @@ -350,9 +350,9 @@ function lexer.cpp(s,filter,options) {IDEN,cpp_vdump}, {NUMBER4,ndump}, {NUMBER5,ndump}, - {STRING3,sdump}, - {STRING1,chdump}, - {STRING2,sdump}, + -- {STRING3,sdump}, + -- {STRING1,chdump}, + -- {STRING2,sdump}, {'^//.-\n',cdump}, {'^/%*.-%*/',cdump}, {'^==',tdump},