From 10b581966735008f5b1dcce1ed1d1fe963f4d01e Mon Sep 17 00:00:00 2001
From: steve donovan <steve.j.donovan@gmail.com>
Date: Fri, 25 Jan 2013 09:09:40 +0200
Subject: [PATCH] new_type() can now specify subfield; Colon mode must be
 explicitly switched on with -C,--colon or  in config.ld

---
 docs/doc.md            | 16 ++++++++++++++++
 ldoc.lua               | 13 ++++++-------
 ldoc/parse.lua         |  2 +-
 tests/styles/colon.lua | 28 ++++++++++++++++++++++++++++
 tests/styles/four.lua  | 17 -----------------
 5 files changed, 51 insertions(+), 25 deletions(-)
 create mode 100644 tests/styles/colon.lua

diff --git a/docs/doc.md b/docs/doc.md
index e7bf27b..d1066b5 100644
--- a/docs/doc.md
+++ b/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
diff --git a/ldoc.lua b/ldoc.lua
index 8fef574..96f636d 100644
--- a/ldoc.lua
+++ b/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
diff --git a/ldoc/parse.lua b/ldoc/parse.lua
index c5e5de9..c962bce 100644
--- a/ldoc/parse.lua
+++ b/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)
diff --git a/tests/styles/colon.lua b/tests/styles/colon.lua
new file mode 100644
index 0000000..ea72ead
--- /dev/null
+++ b/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
diff --git a/tests/styles/four.lua b/tests/styles/four.lua
index f89e42f..123007d 100644
--- a/tests/styles/four.lua
+++ b/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