new_type() can now specify subfield; Colon mode must be explicitly switched on with -C,--colon or in config.ld

docs/doc.md

@@ -470,6 +470,22 @@ And then used as any other type:
 
 This will also create a new module section called 'Macros'.
 
+If your new type has arguments or fields, then specify the name:
+
+    new_type("macro","Macros",false,"param")
+
+(The third argument means that this is not a _project level_ tag)
+
+Then you may say:
+
+    -----
+    -- A macro with arguments.
+    -- @macro second_macro
+    -- @param x the argument
+
+And the arguments will be displayed under the subsection 'param'
+
+
 ## Inferring more from Code
 
 The qualified name of a function will be inferred from any `function` keyword following the

ldoc.lua

@@ -53,7 +53,7 @@ ldoc, a documentation generator for Lua, vs 1.3.1
   -c,--config (default config.ld) configuration name
   -i,--ignore ignore any 'no doc comment or no module' warnings
   -D,--define (default none) set a flag to be used in config.ld
-  -N,--nocolon don't treat colons specially
+  -C,--colon use colon style
   -B,--boilerplate ignore first comment in source files
   --dump                debug output dump
   --filter (default none) filter output as Lua data (e.g pl.pretty.dump)
@@ -160,12 +160,12 @@ function ldoc.add_section (name, title, subname)
 end
 
 -- new tags can be added, which can be on a project level.
-function ldoc.new_type (tag, header, project_level)
+function ldoc.new_type (tag, header, project_level,subfield)
    doc.add_tag(tag,doc.TAG_TYPE,project_level)
    if project_level then
-      ProjectMap:add_kind(tag,header)
+      ProjectMap:add_kind(tag,header,subfield)
    else
-      ModuleMap:add_kind(tag,header)
+      ModuleMap:add_kind(tag,header,subfield)
    end
 end
 
@@ -181,7 +181,7 @@ local ldoc_contents = {
    'alias','add_language_extension','new_type','add_section', 'tparam_alias',
    'file','project','title','package','format','output','dir','ext', 'topics',
    'one','style','template','description','examples',
-   'readme','all','manual_url', 'ignore', 'nocolon','boilerplate',
+   'readme','all','manual_url', 'ignore', 'colon','boilerplate',
    'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler',
 }
 ldoc_contents = tablex.makeset(ldoc_contents)
@@ -250,7 +250,6 @@ if args.module then
    if not fullpath then
       quit(mod)
    else
-      args.nocolon = on_docpath
       args.file = fullpath
       args.module = mod
    end
@@ -348,6 +347,7 @@ local process_file_list = tools.process_file_list
 
 setup_package_base()
 
+override 'colon'
 
 if type(args.file) == 'table' then
    -- this can only be set from config file so we can assume it's already read
@@ -561,7 +561,6 @@ override 'output'
 override 'dir'
 override 'ext'
 override 'one'
-override 'nocolon'
 override 'boilerplate'
 
 if not args.ext:find '^%.' then

ldoc/parse.lua

@@ -96,7 +96,7 @@ end
 local function extract_tags (s,args)
    local preamble,tag_items
    if s:match '^%s*$' then return {} end
-   if not args.nocolon and s:match ':%s' and not s:match '@%a' then
+   if args.colon then --and s:match ':%s' and not s:match '@%a' then
       preamble,tag_items = parse_colon_tags(s)
    else
       preamble,tag_items = parse_at_tags(s)

tests/styles/colon.lua

@@ -0,0 +1,28 @@
+----------------------
+-- Showing off Colon mode.
+-- If you hate @ tags, you can use colons. However, you need to specify colon
+-- mode explicitly -C or --colon, or `colon=true` in the config.ld. Be careful
+-- not to use a colon followed by a space for any other purpose!
+--
+-- So the incantation in this case is `ldoc -C colon.lua`.
+
+-- module: colon
+
+
+--- first useless function.
+-- Optional type specifiers are allowed in this format.
+-- As an extension, '?' is short for '?|'.
+-- Note how these types are rendered!
+-- string: name
+-- int: age
+-- ?person2: options
+-- treturn: ?table|string
+function one (name,age,options)
+end
+
+--- explicit table in colon format.
+-- Note how '!' lets you use a type name directly.
+-- string: surname
+-- string: birthdate
+-- !person2: options
+-- table: person3

tests/styles/four.lua

@@ -15,17 +15,6 @@
 function one (name,age)
 end
 
---- second useless function.
--- If you hate @ tags, you can use colons.
--- Optional type specifiers are allowed in this format.
--- As an extension, '?' is short for '?|'.
--- Note how these types are rendered!
--- string: name
--- int: age
--- ?person2: options
--- treturn: ?table|string
-function two (name,age,options)
-end
 
 --- third useless function.
 -- Can always put comments inline, may
@@ -50,9 +39,3 @@ person = {
 -- @int age
 -- @table person2
 
---- explicit table in colon format.
--- Note how '!' lets you use a type name directly.
--- string: surname
--- string: birthdate
--- !person2: options
--- table: person3