issue #171 doc updates

doc/doc.md

@@ -1204,20 +1204,29 @@ _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'
+  - `prettify_files` prettify the source as well and make links to it; if its value is "show"
+then also index the source 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
+  - `no_lua_ref` stop obsessively trying to create references to standard Lua libraries
   - `backtick_references` whether references in backticks will be resolved. Happens by default
 when using Markdown. When explicit will expand non-references in backticks into `<code>` elements
   - `plain` set to true if `format` is set but you don't want code comments processed
-  - `wrap` ??
+  - `wrap` set to true if you want to allow long names to wrap in the summaries
   -  `manual_url` point to an alternative or local location for the Lua manual, e.g.
 'file:///D:/dev/lua/projects/lua-5.1.4/doc/manual.html'
   - `no_summary` suppress the Contents summary
+  -  `custom_tags` define some new tags, which will be presented after the function description. 
+The format is `{<name>,[title=<name>,}{hidden=false,}{format=nil}}`.  For instance
+`custom_tags={'remark',title='Remarks'}` will add a little `Remarks` section to the docs for any function 
+containing this tag.  `format` can be a function - if not present the default formatter will be used,
+e.g. Markdown
   - `custom_see_handler` function that filters see-references
   - `custom_display_name_handler` function that formats an item's name. The arguments are the item
 and the default function used to format the name. For example, to show an icon or label beside any
 function tagged with a certain tag:
+
       -- define a @callback tag:
       custom_tags = { { 'callback', hidden = true } }
 
@@ -1231,7 +1240,8 @@ function tagged with a certain tag:
 
   - `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.
+  - `template_escape` overrides the usual '#' used for Lua code in templates.
+This needs to be changed if the output format is Markdown, for instance.
 
 _Available functions are:_
 

tests/styles/opt.ld

@@ -1,6 +1,11 @@
--- must have explicit optchain!
-convert_opt=true
-format = 'markdown'
--- want to include project source as well.
-prettify_files='show'
-
+-- must have explicit optchain!
+convert_opt = true
+
+format = 'markdown'
+
+-- want to include project source as well.
+prettify_files = 'show'
+
+-- a custom tag!
+custom_tags = {{'remark',title='Remarks'}}
+

tests/styles/opt.lua

@@ -1,5 +1,6 @@
 ------------
--- Functions with options.
+-- Functions with options and custom tags
+--
 -- @include opt.md
 
 ---- testing [opt]
@@ -7,6 +8,7 @@
 -- @param[opt] two
 -- @param[opt]three
 -- @param[opt] four
+-- @remark use with caution!
 function use_opt (one,two,three,four)
 end