updated changes.md - preparing for release

changes.md

@@ -1,3 +1,30 @@
+## 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

doc/doc.md

@@ -59,6 +59,9 @@ Any module or script must start with a doc comment; any other files are ignored
 warning issued. The only exception is if the module starts with an explicit `module`
 statement.
 
+If your coding standards require a boilerplate copyright notice, then the `-B` flag or
+`boilerplate=true` will make LDoc ignore the first comment of each module.
+
 
 ### Tags
 
@@ -80,7 +83,7 @@ The first important tag to know is the module tag:
 #### Modules: naming and describing your API module
 
 The first thing in your API module should be a name and a description.
-This is how a module is commonly done in Lua 5.2 with a @module tag at the top
+This is how a module is commonly done in Lua 5.2 with a **@module** tag at the top
 which introduces the name:
 
     --- a test module
@@ -113,6 +116,7 @@ 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
@@ -196,6 +200,7 @@ Another kind of module-level type is 'field', such as follows:
 That is, a module may contain exported functions, local functions, tables and fields.
 
 #### Explicitly specifying a function or fields
+
 When the code analysis would lead to the wrong type, you can always be explicit.
 
     --- module contents with explicitly documented field _CONTENTS.
@@ -207,6 +212,7 @@ When the code analysis would lead to the wrong type, you can always be explicit.
     function my_function()
         ...
     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.
@@ -305,8 +311,8 @@ LDoc has a two-layer hierarchy; underneath the project, there are modules, scrip
 (containing code) and examples and 'topics' (containing documentation). These then contain
 items like functions, tables, sections, and so forth.
 
-If you want to document scripts, then use `@script` instead of `@module`. New with 1.4 is
+If you want to document scripts, then use **@script** instead of **@module**. New with 1.4 is
-`@classmod` which is a module which exports a single class.
+**@classmod** which is a module which exports a single class.
 
 
 ## See References
@@ -328,9 +334,9 @@ Here it's assumed that 'split' is a function defined in the same module. If you
 to a function in another module, then the reference has to be qualified.
 
 References to methods use a colon: `myclass:method`; this is for instance how you would
-refer to members of a `@type` section.
+refer to members of a **@type** section.
 
-The example at `tests/complex` shows how @see references are interpreted:
+The example at `tests/complex` shows how **@see** references are interpreted:
 
     complex.util.parse
     complex.convert.basic
@@ -351,7 +357,7 @@ Lua standard function or table, and links to the online Lua manual. So reference
 'table.concat' are handled sensibly.
 
 References may be made inline using the `@{\ref}` syntax. This may appear anywhere in the
-text, and is more flexible than `@see`. In particular, it provides one way to document the
+text, and is more flexible than **@see**. In particular, it provides one way to document the
 type of a parameter or return value when that type has a particular structure:
 
     ------
@@ -406,7 +412,7 @@ online references to the Linux manpages. So in `config.ld` we have:
         return name, url
     end)
 
-'^([%w_]+)%((%d)%)$' both matches the pattern and extracts the name and its section. Then it's
+`^([%w_]+)%((%d)%)$` both matches the pattern and extracts the name and its section. Then it's
 a simple matter of building up the appropriate URL.  The function is expected to
 return _link text_ and _link source_ and the patterns are checked before LDoc tries to resolve
 project references. So it is best to make them match as exactly as possible.
@@ -417,7 +423,7 @@ LDoc requires you to have a module doc comment. If your code style requires
 license blocks that might look like doc comments, then set `boilerplate=true` in your
 configuration and they will be skipped.
 
-This comment does not have to have an explicit `@module` tag and LDoc continues to
+This comment does not have to have an explicit **@module** tag and LDoc continues to
 respect the use of `module()`.
 
 There are three types of 'modules' (i.e. 'project-level'); `module`, a library
@@ -428,23 +434,23 @@ There are some tags which are only useful in module comments: `author`,`copyrigh
 `license` and `release`. These are presented in a special **Info** section in the
 default HTML output.
 
-The `@usage` tag has a somewhat different presentation when used in modules; the text
+The **@usage** tag has a somewhat different presentation when used in modules; the text
 is presented formatted as-is in a code font. If you look at the script `ldoc` in
 this documentation, you can see how the command-line usage is shown. Since coding
 is all about avoiding repetition and the out-of-sync issues that arise,
-the `@usage` tag can appear later in the module, before a long string. For instance,
+the **@usage** tag can appear later in the module, before a long string. For instance,
 the main script of LDoc is [ldoc.lua](https://github.com/stevedonovan/LDoc/blob/master/ldoc.lua)
 and you will see that the usage tag appears on line 36 before the usage string
 presented as help.
 
-`@export` is another module tag that is usually 'detached'. It is for supporting
+**@export** is another module tag that is usually 'detached'. It is for supporting
 modules that wish to explicitly export their functions @{three.lua|at the end}.
 In that example, both `question` and `answer` are local and therefore private to
 the module, but `answer` has been explicitly exported. (If you invoke LDoc with
 the `-a` flag on this file, you will see the documentation for the unexported
 function as well.)
 
-`@set` is a powerful tag which assigns a configuration variable to a value _just for this module_.
+**@set** is a powerful tag which assigns a configuration variable to a value _just for this module_.
 Saying `@set no_summary=true` in a module comment will temporarily disable summary generation when
 the template is expanded. Generally configuration variables that effect template expansion
 are modifiable in this way.  For instance, if you wish that the contents of a particular module
@@ -458,7 +464,7 @@ types in a module: 'Functions', 'Tables' and 'Fields' (There is another default
 sections can be added; the first mechanism is when you @{Adding_new_Tags|define a new type}
 (say 'macro'). Then a new section ('Macros') is created to contain these types.
 
-There is also a way to declare ad-hoc sections using the `@section` tag.
+There is also a way to declare ad-hoc sections using the **@section** tag.
 The need occurs when a module has a lot of functions that need to be put into logical
 sections.
 
@@ -507,7 +513,7 @@ with the LuaDoc `class` tag.)
 
 A section continues until the next section is found, `@section end`, or end of file.
 
-You can put items into an implicit section using the @within tag. This allows you to put
+You can put items into an implicit section using the **@within tag**. This allows you to put
 adjacent functions in different sections, so that you are not forced to order your code
 in a particular way.
 
@@ -518,7 +524,7 @@ and the advantage that methods can be put into sections.
 Sometimes a module may logically span several files, which can easily happen with large
 There will be a master module with name
 'foo' and other files which when required add functions to that module. If these files have
-a @submodule tag, their contents will be placed in the master module documentation. However,
+a **@submodule** tag, their contents will be placed in the master module documentation. However,
 a current limitation is that the master module must be processed before the submodules.
 
 See the `tests/submodule` example for how this works in practice.
@@ -679,8 +685,8 @@ See @{mylib.c} for the full example.
 
 1.4 introduces basic support for [Moonscript](http://moonscript.org). Moonscript module
 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
-put explicitly into a separate section.
+and methods put implicitly into a separate section.
 
 ## Basic Usage
 
@@ -915,7 +921,7 @@ can suppress the contents summary with `no_summary`.
 
 A basic customization is to override the default UTF-8 encoding using `charset`. For instance,
 Brazillian software would find it useful to put `charset='ISO-8859-1'` in `config.ld`, or use
-the @charset tag for individual files.
+the **@charset** tag for individual files.
 
 Setting `no_return_or_parms` to `true` will suppress the display of 'param' and 'return'
 tags. This may appeal to programmers who dislike the traditional @tag soup xDoc style and
@@ -957,7 +963,7 @@ and writer-generated documentation using different tools, and having to match th
 
 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
-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.
 
 The line in the `config.ld` that enables this is:
@@ -1048,7 +1054,7 @@ 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"; this also applies
+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:
@@ -1079,8 +1085,8 @@ defined as a tag plus a set of modifiers.  So `tparam` is defined as:
 
     alias('tparam',{'param',modifiers={type="$1"}})
 
-As an extension, you're allowed to use '@param' tags in table definitions. This makes it
+As an extension, you're allowed to use **@param** tags in table definitions. This makes it
-possible to use type alias like '@string' to describe fields, since they will expand to
+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,
@@ -1113,7 +1119,7 @@ then LDoc can present this as the default value for this optional argument.
 (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
-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
 return multiple values.  However, being a dynamic language it may return a single value if
 successful and two values (`nil`,an error message) if there is an error. This is in fact the
 convention for returning 'normal' errors (like 'file not found') as opposed to parameter errors
@@ -1133,7 +1139,7 @@ as a group:
 This is the first function in @{multiple.lua}, and the [output](http://stevedonovan.github.io/ldoc/examples/multiple)
 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.
 
 Currently the `type`,`opt` and `<digit>` modifiers are the only ones known and used by LDoc when generating HTML
@@ -1162,7 +1168,7 @@ of files and directories.
 template. In `config.ld` they may also be `true`, meaning use the same directory as the
 configuration file.
   - `merge` allow documentation from different files to be merged into modules without
-explicit @submodule tag
+explicit **@submodule** tag
 
 _These only appear in the configuration file:_
 
@@ -1171,7 +1177,7 @@ _These only appear in the configuration file:_
   - `examples` a directory or file: can be a table
   - `readme` or `topics` readme files (to be processed with Markdown)
   - `pretty` code prettify 'lua' (default) or 'lxsh'
-  - `charset` use if you want to override the UTF-8 default (also @charset in files)
+  - `charset` use if you want to override the UTF-8 default (also **@charset** in files)
   - `sort` set if you want all items in alphabetical order
   - `no_return_or_parms` don't show parameters or return values in output
   - `backtick_references` whether references in backticks will be resolved. Happens by default
@@ -1195,7 +1201,7 @@ function tagged with a certain tag:
         end
         return default_handler(item)
       end
-      
+
   - `not_luadoc` set to `true` if the docs break LuaDoc compatibility
   - `no_space_before_args` set to `true` if you do not want a space between a function's name and its arguments.
   - `template_escape` overrides the usual '#' used for Lua code in templates. This needs to be changed if the output format is Markdown, for instance.
@@ -1328,7 +1334,7 @@ The basic data structure is straightforward: it is an array of 'modules' (projec
 entities, including scripts) which each contain an `item` array (functions, tables and so
 forth).
 
-For instance, to find all functions which don't have a @return tag:
+For instance, to find all functions which don't have a **@return** tag:
 
     return {
        filter = function (t)
@@ -1342,8 +1348,8 @@ For instance, to find all functions which don't have a @return tag:
        end
     }
 
-The internal naming is not always so consistent; `ret` corresponds to @return, and `params`
+The internal naming is not always so consistent; `ret` corresponds to **@return**, and `params`
-corresponds to @param.  `item.params` is an array of the function parameters, in order; it
+corresponds to **@param**.  `item.params` is an array of the function parameters, in order; it
 is also a map from these names to the individual descriptions of the parameters.
 
 `item.modifiers` is a table where the keys are the tags and the values are arrays of