Bumped version to 1.4.3; doc updates; C lexer ignores strings (which it handles badly)
steve donovan
9 years ago
| 0 | ## Version 1.4.2 | |
| 1 | ||
| 2 | ### Features | |
| 3 | ||
| 4 | * Can define fields/properties of objects; `readonly` modifier supported (#93) | |
| 5 | * Can switch off auto-linking to Lua manual with `no_lua_ref` | |
| 6 | * Module sorting is off by default, use `sort_modules=true` | |
| 7 | * References to 'classes' now work properly | |
| 8 | * Option to use first Markdown title instead of file names with `use_markdown_titles` | |
| 9 | * Automatic `Metamethods` and `Methods` sections generated for `classmod` classes | |
| 10 | * `unqualified=true` to strip package names on sidebar (#110) | |
| 11 | * Custom tags (which may be hidden) | |
| 12 | * Custom Display Name handlers | |
| 13 | ||
| 14 | ### Fixes | |
| 15 | ||
| 16 | * stricter about doc comments, now excludes common '----- XXXXX ----' pattern | |
| 17 | * no longer expects space after `##` in Markdown (#96) | |
| 18 | * Section lookup was broken | |
| 19 | * With `export` tag, decide whether method is static or not | |
| 20 | * `classmod` classes now respect custom sections (#113) | |
| 21 | * Minor issues with prettification | |
| 22 | * Command-line flags set explicitly take precendence over configuration file values. | |
| 23 | * Boilerplate Lua block comment ignored properly (#137) | |
| 24 | * Inline links with underscores sorted (#22) | |
| 25 | * Info section ordering is now consistent (#150) | |
| 26 | ||
| 27 | ## Version 1.4.0 | |
| 28 | ||
| 29 | ### Features | |
| 30 | ||
| 31 | * `sort=true` to sort items within sections alphabetically | |
| 32 | * `@set` tag in module comments; e.g, can say `@set sort=true` | |
| 33 | * `@classmod` tag for defining modules that export one class | |
| 34 | * can generate Markdown output | |
| 35 | * Can prettify C as well as Lua code with built-in prettifier | |
| 36 | * lfs and lpeg references understood | |
| 37 | * 'pale' template available | |
| 38 | * multiple return groups | |
| 39 | * experimental `@error` tag | |
| 40 | * Moonscript and plain C support | |
| 41 | ||
| 42 | ||
| 43 | ### Fixes | |
| 44 | ||
| 45 | * works with non-compatibily Lua 5.2, including `markdown.lua` | |
| 46 | * module names can not be types | |
| 47 | * all `builtin` Lua files are requirable without `module` | |
| 48 | * backticks expand in copyright and other 'info' tabs | |
| 49 | * `-m` tries harder to resolve methods | |
| 50 | * auto-scroll in navigation area to avoid breaking identifiers | |
| 51 | * better error message for non-luadoc-compatible behaviour | |
| 52 | * custom see references fixed | |
| 53 | ||
| 54 | ||
| 55 | ||
| 0 | ## Version 1.4.3 | |
| 1 | ||
| 2 | ### Features | |
| 3 | ||
| 4 | * @include tag for including Markdown documentation file directly into module docstring | |
| 5 | * `prettify_files` makes per-item links to prettified source. | |
| 6 | * link targets rendered in bright yellow to make referenced functions more obvious | |
| 7 | * add update time to footer of page | |
| 8 | * better C support: `global_lookup=true` - invoked when `parse_extra={C=true}` | |
| 9 | * `kind_names` can override names used in sidebar | |
| 10 | ||
| 11 | ### Fixes | |
| 12 | ||
| 13 | * `all=true` in `config.ld` did not work. | |
| 14 | * `dont_escape_underscore` logic fixed: do not use in prettified code blocks | |
| 15 | * check that `ldoc` config exists before checking field values | |
| 16 | * annotation rendering fixed | |
| 17 | * summary not dropped when using `type` sections | |
| 18 | * directory as argument case was broken | |
| 19 | * parameter names which were List methods causing mayhem | |
| 20 | * files are processed in fixed order across platforms | |
| 21 | ||
| 22 | ## Version 1.4.2 | |
| 23 | ||
| 24 | ### Features | |
| 25 | ||
| 26 | * Can define fields/properties of objects; `readonly` modifier supported (#93) | |
| 27 | * Can switch off auto-linking to Lua manual with `no_lua_ref` | |
| 28 | * Module sorting is off by default, use `sort_modules=true` | |
| 29 | * References to 'classes' now work properly | |
| 30 | * Option to use first Markdown title instead of file names with `use_markdown_titles` | |
| 31 | * Automatic `Metamethods` and `Methods` sections generated for `classmod` classes | |
| 32 | * `unqualified=true` to strip package names on sidebar (#110) | |
| 33 | * Custom tags (which may be hidden) | |
| 34 | * Custom Display Name handlers | |
| 35 | ||
| 36 | ### Fixes | |
| 37 | ||
| 38 | * stricter about doc comments, now excludes common '----- XXXXX ----' pattern | |
| 39 | * no longer expects space after `##` in Markdown (#96) | |
| 40 | * Section lookup was broken | |
| 41 | * With `export` tag, decide whether method is static or not | |
| 42 | * `classmod` classes now respect custom sections (#113) | |
| 43 | * Minor issues with prettification | |
| 44 | * Command-line flags set explicitly take precendence over configuration file values. | |
| 45 | * Boilerplate Lua block comment ignored properly (#137) | |
| 46 | * Inline links with underscores sorted (#22) | |
| 47 | * Info section ordering is now consistent (#150) | |
| 48 | ||
| 49 | ## Version 1.4.0 | |
| 50 | ||
| 51 | ### Features | |
| 52 | ||
| 53 | * `sort=true` to sort items within sections alphabetically | |
| 54 | * `@set` tag in module comments; e.g, can say `@set sort=true` | |
| 55 | * `@classmod` tag for defining modules that export one class | |
| 56 | * can generate Markdown output | |
| 57 | * Can prettify C as well as Lua code with built-in prettifier | |
| 58 | * lfs and lpeg references understood | |
| 59 | * 'pale' template available | |
| 60 | * multiple return groups | |
| 61 | * experimental `@error` tag | |
| 62 | * Moonscript and plain C support | |
| 63 | ||
| 64 | ||
| 65 | ### Fixes | |
| 66 | ||
| 67 | * works with non-compatibily Lua 5.2, including `markdown.lua` | |
| 68 | * module names can not be types | |
| 69 | * all `builtin` Lua files are requirable without `module` | |
| 70 | * backticks expand in copyright and other 'info' tabs | |
| 71 | * `-m` tries harder to resolve methods | |
| 72 | * auto-scroll in navigation area to avoid breaking identifiers | |
| 73 | * better error message for non-luadoc-compatible behaviour | |
| 74 | * custom see references fixed | |
| 75 | ||
| 76 | ||
| 77 |
| 142 | 142 | You can also give the function name itself as an explicit tag, |
| 143 | 143 | which is especially useful when documenting a Lua api exported by C code: |
| 144 | 144 | |
| 145 | /// A C function which is exported to Lua with another name, | |
| 146 | // because the ways of C can be mysterious! | |
| 147 | // @function our_nice_function | |
| 148 | int _some_function_for_lua(lua_State* l) { | |
| 149 | .... | |
| 150 | } | |
| 145 | ```C | |
| 146 | /// A C function which is exported to Lua with another name, | |
| 147 | // because the ways of C can be mysterious! | |
| 148 | // @function our_nice_function | |
| 149 | int _some_function_for_lua(lua_State* l) { | |
| 150 | .... | |
| 151 | } | |
| 152 | ``` | |
| 151 | 153 | |
| 152 | 154 | The tags basically add all the detail that cannot be derived from the source code |
| 153 | 155 | automatically. |
| 188 | 190 | end |
| 189 | 191 | |
| 190 | 192 | ... |
| 191 | Of course there is also the 'module' tag which you have already seen. | |
| 192 | 193 | |
| 193 | 194 | #### Tables and constant values (fields) |
| 194 | 195 | |
| 215 | 216 | |
| 216 | 217 | The rule followed here is `NAME = <table-constructor>`. If LDoc can't work out the name and |
| 217 | 218 | type from the following code, then a warning will be issued, pointing to the file and |
| 218 | location. | |
| 219 | location. Only single-level tables are currently supported, and the fields must be valid | |
| 220 | identifiers. | |
| 219 | 221 | |
| 220 | 222 | Another kind of module-level type is 'field', such as follows: |
| 221 | 223 | |
| 238 | 240 | ... |
| 239 | 241 | end |
| 240 | 242 | |
| 241 | As mentioned before, this is often especially useful in C where things | |
| 242 | may look different in the C code than they will in the final Lua api which | |
| 243 | you want to document. | |
| 243 | This is especially useful in C where the function declarations | |
| 244 | are different from final Lua api which you are documenting. | |
| 244 | 245 | |
| 245 | 246 | ### Doing modules the Lua 5.1 way |
| 246 | 247 | |
| 292 | 293 | ### Local functions |
| 293 | 294 | |
| 294 | 295 | Apart from exported functions, a module usually contains local functions. By default, LDoc |
| 295 | does not include these in the documentation, but they can be enabled using the `--all` flag. | |
| 296 | does not include these in the documentation, but they can be enabled using the `--all` flag, | |
| 297 | or `all=true` in `config.ld`. | |
| 296 | 298 | They can be documented just like 'public' functions: |
| 297 | 299 | |
| 298 | 300 | --- it's clear that boo is local from context. |
| 405 | 407 | The link text can be changed from the default by the extended syntax `@{\ref|text}. |
| 406 | 408 | |
| 407 | 409 | You can also put references in backticks, like `\`stdvars\``. This is commonly used in |
| 408 | Markdown to indicate code, so it comes naturally when writing documents. It is controlled by | |
| 409 | the configuration variable `backtick_references` or the `backtick` format; | |
| 410 | Markdown to indicate code, so it comes naturally when writing documents. The difference | |
| 411 | is that the backticked expression does not have to be a reference and then will appear | |
| 412 | in code style; with @ references you will get a warning for unrecognized symbols | |
| 413 | and the result will be rendered as '???'. | |
| 414 | ||
| 415 | It is controlled by the configuration variable `backtick_references` or the `backtick` format; | |
| 410 | 416 | the default is `true` if you use Markdown in your project, but can be specified explicitly |
| 411 | 417 | in `config.ld`. |
| 412 | 418 | |
| 943 | 949 | will give a _one-column_ layout, which can be easier to use as a programming reference. You |
| 944 | 950 | can suppress the contents summary with `no_summary`. |
| 945 | 951 | |
| 952 | If you don't like the usual top-level names, like 'Module' and 'Topics', you can override these | |
| 953 | with `kind_names` in `config.ld`. For instance, in Penlight I use `kind_names={topic='Manual',module='Libraries'}` | |
| 954 | ||
| 946 | 955 | ## Customizing the Page |
| 947 | 956 | |
| 948 | 957 | A basic customization is to override the default UTF-8 encoding using `charset`. For instance, |
| 1010 | 1019 | [lxsh](https://github.com/xolox/lua-lxsh) |
| 1011 | 1020 | can be used (available from LuaRocks) if you want something more powerful. `pretty='lxsh'` will |
| 1012 | 1021 | cause `lxsh` to be used, if available. |
| 1022 | ||
| 1023 | Sometimes the best examples you have are your source files. `prettify_files=true` will prettify | |
| 1024 | all sources, and generate per-function links to the source. | |
| 1013 | 1025 | |
| 1014 | 1026 | ## Readme files |
| 1015 | 1027 | |
| 1115 | 1127 | possible to use type aliases like **@string** to describe fields, since they will expand to |
| 1116 | 1128 | 'param'. |
| 1117 | 1129 | |
| 1130 | ||
| 1118 | 1131 | Another modifier understood by LDoc is `opt`. For instance, |
| 1119 | 1132 | |
| 1120 | 1133 | ---- testing [opt] |
| 1122 | 1135 | -- @param[opt] two |
| 1123 | 1136 | -- @param three |
| 1124 | 1137 | -- @param[opt] four |
| 1125 | function two (one,two,three,four) | |
| 1138 | function fun (one,two,three,four) | |
| 1126 | 1139 | end |
| 1127 | ----> displayed as: two (one [, two], three [, four]) | |
| 1128 | ||
| 1129 | This modifier can also be used with type aliases. If a value is given for `opt` | |
| 1130 | then LDoc can present this as the default value for this optional argument. | |
| 1140 | ----> displayed as: fun (one [, two], three [, four]) | |
| 1141 | ||
| 1142 | A more typical Lua API would have a chain of optional arguments, like so: | |
| 1143 | ||
| 1144 | ---- a chain of options | |
| 1145 | -- @param one | |
| 1146 | -- @param[opt] two | |
| 1147 | -- @param[optchain] three | |
| 1148 | -- @param[optchain] four | |
| 1149 | function fun (one,two,three,four) | |
| 1150 | end | |
| 1151 | ----> displayed as: fun (one [, two [, three [, four]]]) | |
| 1152 | ||
| 1153 | This is a bit tedious to type, so the rule is that a series of 'opt' modifiers will be interpreted | |
| 1154 | as 'opt','optchain'.... . If you want to be explicit, then do `convert_opt=true` in your | |
| 1155 | `config.ld`. | |
| 1156 | ||
| 1157 | If a value is given for `opt`then LDoc can present this as the default value for this optional argument. | |
| 1158 | ||
| 1159 | This modifier can also be used with typed param aliases. | |
| 1131 | 1160 | |
| 1132 | 1161 | --- a function with typed args. |
| 1133 | 1162 | -- If the Lua function has varargs, then |
| 1140 | 1169 | function one (name,age,...) |
| 1141 | 1170 | end |
| 1142 | 1171 | ----> displayed as: one (name, age [, calender='gregorian' [, offset=0]]) |
| 1143 | ||
| 1144 | 1172 | |
| 1145 | 1173 | (See @{four.lua}, rendered [here](http://stevedonovan.github.io/ldoc/examples/four)) |
| 1146 | 1174 | |
| 288 | 288 | </div> <!-- id="content" --> |
| 289 | 289 | </div> <!-- id="main" --> |
| 290 | 290 | <div id="about"> |
| 291 | <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.2</a></i> | |
| 291 | <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i> | |
| 292 | 292 | <i style="float:right;">Last updated $(ldoc.updatetime) </i> |
| 293 | 293 | </div> <!-- id="about" --> |
| 294 | 294 | </div> <!-- id="container" --> |