Tweaks to opt/optchain: (optional) is emitted after optional arguments without defaults. convert_opts (counter-intuitively) disables automatic opt->optchain promotion

ldoc.lua

@@ -233,7 +233,7 @@ local ldoc_contents = {
    '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', 'custom_display_name_handler', 'kind_names', 'custom_references',
-   'dont_escape_underscore','global_lookup','prettify_files'   
+   'dont_escape_underscore','global_lookup','prettify_files','convert_opt'
 }
 ldoc_contents = tablex.makeset(ldoc_contents)
 

ldoc/doc.lua

@@ -382,7 +382,7 @@ function File:finish()
                   item.section = item.type
                end
             elseif item.tags.within then -- ad-hoc section...
-					item.section = item.tags.within
+               item.section = item.tags.within
             else -- otherwise, just goes into the default sections (Functions,Tables,etc)
                item.section = item.type;
             end
@@ -807,8 +807,9 @@ 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
+   -- a number of trailing [opt]s will be usually converted to [opt],[optchain],...
+   -- *unless* a person uses convert_opt.
+   if pmods and not doc.ldoc.convert_opt then
       local m = pmods[#names]
       if m and m.opt then
          m.optchain = m.opt
@@ -855,11 +856,11 @@ function Item:type_of_param(p)
    return mparam and mparam.type or ''
 end
 
+-- default value for param; if optional but no default, it's just `true`.
 function Item:default_of_param(p)
    local m = self:param_modifiers(p)
    if not m then return nil end
    local opt = m.optchain or m.opt
-   if opt == true then return nil end
    return opt
 end
 

ldoc/html/ldoc_ltp.lua

@@ -186,7 +186,9 @@ return [==[
             <span class="types">$(tp)</span>
 #       end
         $(M(item.params.map[p],item))
-#       if def then
+#       if def == true then
+         (<em>optional</em>)
+#      elseif def then
          (<em>default</em> $(def))
 #       end
 #       if item:readonly(p) then