Bumped version to 1.4.3; doc updates; C lexer ignores strings (which it handles badly)

changes.md

@@ -1,56 +1,78 @@
-## Version 1.4.2
+## Version 1.4.3
-
+
-### Features
+### Features
-
+
-  * Can define fields/properties of objects; `readonly` modifier supported (#93)
+  * @include tag for including Markdown documentation file directly into module docstring
-  * Can switch off auto-linking to Lua manual with `no_lua_ref`
+  * `prettify_files` makes per-item links to prettified source.
-  * Module sorting is off by default, use `sort_modules=true`
+  * link targets rendered in bright yellow to make referenced functions more obvious
-  * References to 'classes' now work properly
+  * add update time to footer of page
-  * Option to use first Markdown title instead of file names with `use_markdown_titles`
+  * better C support: `global_lookup=true` - invoked when `parse_extra={C=true}`
-  * Automatic `Metamethods` and `Methods` sections generated for `classmod` classes
+  * `kind_names` can override names used in sidebar
-  * `unqualified=true` to strip package names on sidebar (#110)
+  
-  * Custom tags (which may be hidden)
+### Fixes
-  * Custom Display Name handlers
+
-
+  * `all=true` in `config.ld` did not work.
-### Fixes
+  * `dont_escape_underscore` logic fixed: do not use in prettified code blocks
-
+  * check that `ldoc` config exists before checking field values
-  * stricter about doc comments, now excludes common '----- XXXXX ----' pattern
+  * annotation rendering fixed
-  * no longer expects space after `##` in Markdown (#96)
+  * summary not dropped when using `type` sections
-  * Section lookup was broken
+  * directory as argument case was broken
-  * With `export` tag, decide whether method is static or not
+  * parameter names which were List methods causing mayhem
-  * `classmod` classes now respect custom sections (#113)
+  * files are processed in fixed order across platforms
-  * Minor issues with prettification
+
-  * Command-line flags set explicitly take precendence over configuration file values.
+## Version 1.4.2
-  * Boilerplate Lua block comment ignored properly (#137)
+
-  * Inline links with underscores sorted (#22)
+### Features
-  * Info section ordering is now consistent (#150)
+
-
+  * Can define fields/properties of objects; `readonly` modifier supported (#93)
-## Version 1.4.0
+  * Can switch off auto-linking to Lua manual with `no_lua_ref`
-
+  * Module sorting is off by default, use `sort_modules=true`
-### Features
+  * References to 'classes' now work properly
-
+  * Option to use first Markdown title instead of file names with `use_markdown_titles`
-  * `sort=true` to sort items within sections alphabetically
+  * Automatic `Metamethods` and `Methods` sections generated for `classmod` classes
-  * `@set` tag in module comments; e.g, can say `@set sort=true`
+  * `unqualified=true` to strip package names on sidebar (#110)
-  * `@classmod` tag for defining modules that export one class
+  * Custom tags (which may be hidden)
-  * can generate Markdown output
+  * Custom Display Name handlers
-  * Can prettify C as well as Lua code with built-in prettifier
+
-  * lfs and lpeg references understood
+### Fixes
-  * 'pale' template available
+
-  * multiple return groups
+  * stricter about doc comments, now excludes common '----- XXXXX ----' pattern
-  * experimental `@error` tag
+  * no longer expects space after `##` in Markdown (#96)
-  * Moonscript and plain C support
+  * Section lookup was broken
-
+  * With `export` tag, decide whether method is static or not
-
+  * `classmod` classes now respect custom sections (#113)
-### Fixes
+  * Minor issues with prettification
-
+  * Command-line flags set explicitly take precendence over configuration file values.
-  * works with non-compatibily Lua 5.2, including `markdown.lua`
+  * Boilerplate Lua block comment ignored properly (#137)
-  * module names can not be types
+  * Inline links with underscores sorted (#22)
-  * all `builtin` Lua files are requirable without `module`
+  * Info section ordering is now consistent (#150)
-  * backticks expand in copyright and other 'info' tabs
+
-  * `-m` tries harder to resolve methods
+## Version 1.4.0
-  * auto-scroll in navigation area to avoid breaking identifiers
+
-  * better error message for non-luadoc-compatible behaviour
+### Features
-  * custom see references fixed
+
-
+  * `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
+
+
+

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,
+```C
-    // because the ways of C can be mysterious!
+/// A C function which is exported to Lua with another name,
-    // @function our_nice_function
+// because the ways of C can be mysterious!
-    int _some_function_for_lua(lua_State* l) {
+// @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 = <table-constructor>`. 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
+This is especially useful in C where the function declarations
-may look different in the C code than they will in the final Lua api which
+are different from final Lua api which you are documenting.
-you want to document.
 
 ### 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
+Markdown to indicate code, so it comes naturally when writing documents. The difference
-the configuration variable `backtick_references` or the `backtick` format;
+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`
+    ---- a chain of options
-then LDoc can present this as the default value for this optional argument.
+    -- @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

ldoc/html/ldoc_ltp.lua

@@ -289,7 +289,7 @@ return [==[
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.2</a></i>
+<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
 <i style="float:right;">Last updated $(ldoc.updatetime) </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->

ldoc/lexer.lua

@@ -350,9 +350,9 @@ function lexer.cpp(s,filter,options)
             {IDEN,cpp_vdump},
             {NUMBER4,ndump},
             {NUMBER5,ndump},
-            {STRING3,sdump},
+          --  {STRING3,sdump},
-            {STRING1,chdump},
+          --  {STRING1,chdump},
-            {STRING2,sdump},
+          --  {STRING2,sdump},
             {'^//.-\n',cdump},
             {'^/%*.-%*/',cdump},
             {'^==',tdump},