Unify the way optional params are displayed.

- Add -P,--plain_params setting for no brackets or defaults in param list.
- Params with modifiers like [type=?foo] have brackets in param list.
- Params with modifiers like [opt] show up as "optional" in param description.

ldoc.lua

@@ -61,6 +61,7 @@ ldoc, a documentation generator for Lua, vs 1.4.0
   -M,--merge allow module merging
   -S,--simple no return or params, no summary
   -O,--one one-column output layout
+  -P,--plain_params    don't show brackets or default values in param lists
   --dump                debug output dump
   --filter (default none) filter output as Lua data (e.g pl.pretty.dump)
   --tags (default none) show all references to given tags, comma-separated
@@ -200,7 +201,7 @@ local ldoc_contents = {
    'boilerplate','merge', 'wrap', 'not_luadoc', 'template_escape','merge_error_groups',
    'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler',
    'no_space_before_args','parse_extra','no_lua_ref','sort_modules','use_markdown_titles',
-   'unqualified',
+   'plain_params', 'unqualified',
 }
 ldoc_contents = tablex.makeset(ldoc_contents)
 
@@ -317,6 +318,9 @@ if type(ldoc.custom_tags) == 'table' then -- custom tags
   end
 end -- custom tags
 
+override 'plain_params'
+ldoc.plain_params = args.plain_params
+
 local source_dir = args.file
 if type(source_dir) == 'table' then
    source_dir = source_dir[1]

ldoc/doc.lua

@@ -791,21 +791,30 @@ function split_iden (name)
 end
 
 function build_arg_list (names,pmods)
+   -- if plain_params option is set, return a simple parameter list.
+   if doc.ldoc.plain_params then
+      return '(' .. table.concat(names, ', ') .. ')'
+   end
    -- build up the string representation of the argument list,
    -- using any opt and optchain modifiers if present.
    -- For instance, '(a [, b])' if b is marked as optional
    -- with @param[opt] b
    local buffer, npending = { }, 0
    local function acc(x) table.insert(buffer, x) end
+   local function get_opt(m)
+      return m and (m.opt or m.type and not not m.type:match '^%?')
+   end
    -- a number of trailing [opt]s can be safely converted to [opt],[optchain],...
    if pmods then
       local m = pmods[#names]
-      if m and m.opt then
+      local opt = get_opt(m)
-         m.optchain = m.opt
+      if opt then
+         m.optchain = opt
          for i = #names-1,1,-1 do
             m = pmods[i]
-            if not m or not m.opt then break end
+            opt = get_opt(m)
-            m.optchain = m.opt
+            if not opt then break end
+            m.optchain = opt
          end
       end
    end
@@ -817,7 +826,7 @@ function build_arg_list (names,pmods)
             acc ((']'):rep(npending))
             npending=0
          end
-         opt = m.optchain or m.opt
+         opt = m.optchain or get_opt(m)
          if opt then
             acc('[')
             npending=npending+1

ldoc/html.lua

@@ -181,8 +181,10 @@ function html.generate_output(ldoc, args, project)
       return type(t) == 'table' and t.append
    end
 
-   function ldoc.typename (tp)
+   function ldoc.typename (tp, pmods)
-      if not tp or tp == '' or tp:match '^@' then return '' end
+      if not tp or tp == '' or tp:match '^@' then
+         return pmods and pmods.opt and 'optional' or ''
+      end
       local optional
       -- ?<type> is short for ?nil|<type>
       if tp:match("^%?") and not tp:match '|' then
@@ -194,6 +196,9 @@ function html.generate_output(ldoc, args, project)
          tp = tp2
       end
 
+      if pmods and pmods.opt then
+         optional = true
+      end
       local types = {}
       for name in tp:gmatch("[^|]+") do
          local sym = name:match '([%w%.%:]+)'

ldoc/html/ldoc_ltp.lua

@@ -177,7 +177,9 @@ return [==[
         <ul>
 #     end
 #     for p in iter(param) do
-#        local name,tp,def = item:display_name_of(p), ldoc.typename(item:type_of_param(p)), item:default_of_param(p)
+#        local name = item:display_name_of(p)
+#        local tp = ldoc.typename(item:type_of_param(p), item:param_modifiers(p))
+#        local def = item:default_of_param(p)
         <li><span class="parameter">$(name)</span>
 #       if tp ~= '' then
             <span class="types">$(tp)</span>