merging trailing [opt] as [optchain]s. Trying to solve 'self' references in modules

docs/doc.md

@@ -432,10 +432,15 @@ Since 1.3, LDoc allows the use of _colons_ instead of @.
     --- a simple function.
     -- string name person's name
     -- int: age age of person
-    -- treturn: ?nil|string
+    -- !person: person object
+    -- treturn: ?string
     -- function check(name,age)
 
+However, you must either use the `--colon` flag or set `colon=true` in your `config.ld`.
 
+In this style, types may be used directly if prefixed with '!' or '?' (for type-or-nil)
+
+(see `tests/styles/colon.lua`)
 
 ## Adding new Tags
 
@@ -550,6 +555,10 @@ An unknown extension can be associated with a language using a call like
 `add_language_extension('lc','c')` in `config.ld`. (Currently the language can only be 'c'
 or 'lua'.)
 
+An LDoc feature which is particularly useful for C extensions is _module merging_. If several
+files are all marked as `@module lib` then a single module `lib` is generated, containing all
+the docs from the separate files.
+
 See 'tests/examples/mylib.c' for the full example.
 
 ## Basic Usage
@@ -926,6 +935,34 @@ As an extension, you're allowed to use '@param' tags in table definitions. This
 possible to use type alias like '@string' to describe fields, since they will expand to
 'param'.
 
+Another modifier understood by LDoc is `opt`. For instance,
+
+    ---- testing [opt]
+    -- @param one
+    -- @param[opt] two
+    -- @param three
+    -- @param[opt] four
+    function two (one,two,three,four)
+    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
+then LDoc can present this as the default value for this optional argument.
+
+    --- a function with typed args.
+    -- If the Lua function has varargs, then
+    -- you may document an indefinite number of extra arguments!
+    -- @string name person's name
+    -- @int age
+    -- @string[opt='gregorian'] calender optional calendar
+    -- @int[opt=0] offset optional offset
+    -- @treturn string
+    function one (name,age,...)
+    end
+    ----> displayed as: one (name, age [, calender='gregorian' [, offset=0]])
+
+(See `tests/styles/four.lua`)
+
 ## Fields allowed in `config.ld`
 
 These mostly have the same meaning as the corresponding parameters:

ldoc/doc.lua

@@ -663,6 +663,18 @@ function build_arg_list (names,pmods)
    -- with @param[opt] b
    local buffer, npending = { }, 0
    local function acc(x) table.insert(buffer, x) end
+   -- a number of trailing [opt]s can be safely converted to [opt],[optchain],...
+   if pmods then
+      local m = pmods[#names]
+      if m.opt then
+         m.optchain = m.opt
+         for i = #names-1,1,-1 do
+            m = pmods[i]
+            if not m.opt then break end
+            m.optchain = m.opt
+         end
+      end
+   end
    for i = 1, #names  do
       local m = pmods and pmods[i]
       local opt
@@ -671,7 +683,7 @@ function build_arg_list (names,pmods)
             acc ((']'):rep(npending))
             npending=0
          end
-         opt = m.opt or m.optchain
+         opt = m.optchain or m.opt
          if opt then
             acc(' [')
             npending=npending+1

ldoc/markup.lua

@@ -35,7 +35,7 @@ local function resolve_inline_references (ldoc, txt, item, plain)
          label = label:gsub('_','\\_')
       end
       local html = ldoc.href(ref) or '#'
-      label = label or '?que'
+      label = label or qname
       local res = ('<a href="%s">%s</a>'):format(html,label)
       return res
    end))

tests/styles/four.lua

@@ -14,11 +14,19 @@
 -- @string name person's name
 -- @int age
 -- @string[opt='gregorian'] calender optional calendar
--- @int[optchain=0] offset optional offset
+-- @int[opt=0] offset optional offset
 -- @treturn string
 function one (name,age,...)
 end
 
+---- testing [opt]
+-- @param one
+-- @param[opt] two
+-- @param three
+-- @param[opt] four
+function two (one,two,three,four)
+end
+
 
 --- third useless function.
 -- Can always put comments inline, may