From 38c8f187b3a577ded19c3cf9c84caa490353e72a Mon Sep 17 00:00:00 2001
From: steve donovan <steve.j.donovan@gmail.com>
Date: Fri, 2 Mar 2012 13:19:34 +0200
Subject: [PATCH] improved varargs support; updated example to show this and
 tparam usage

---
 ldoc/doc.lua              | 18 ++++++++++++------
 tests/example/config.ld   |  2 ++
 tests/example/mod1.lua    | 21 +++++++++++++++++++++
 tests/example/modtest.lua | 13 +++++++++++--
 4 files changed, 46 insertions(+), 8 deletions(-)

diff --git a/ldoc/doc.lua b/ldoc/doc.lua
index 8846181..b9cd3b0 100644
--- a/ldoc/doc.lua
+++ b/ldoc/doc.lua
@@ -338,6 +338,7 @@ end
 
 function Item:finish()
    local tags = self.tags
+   local quote = tools.quote
    self.name = read_del(tags,'name')
    self.type = read_del(tags,'class')
    self.modifiers = extract_tag_modifiers(tags)
@@ -375,20 +376,19 @@ function Item:finish()
       end
       -- not all arguments may be commented: we use the formal arguments
       -- if available as the authoritative list, and warn if there's an inconsistency.
-      -- A formal argument of ... may match any number of params, however.
       if self.formal_args then
          local fargs = self.formal_args
          if #fargs ~= 1 then
             local pnames, pcomments = names, comments
             names, comments = List(),List()
+            local varargs = fargs[#fargs] == '...'
             for i,name in ipairs(fargs) do
                if params then -- explicit set of param tags
-                  local varargs = name == '...'
                   if pnames[i] ~= name and not varargs then
                      if pnames[i] then
-                        self:warning("param and formal argument name mismatch: '"..name.."' '"..pnames[i].."'")
+                        self:warning("param and formal argument name mismatch: "..quote(name).." "..quote(pnames[i]))
                      else
-                        self:warning("undocumented formal argument: '"..name.."'")
+                        self:warning("undocumented formal argument: "..quote(name))
                      end
                   elseif varargs then
                      name = pnames[i]
@@ -398,9 +398,15 @@ function Item:finish()
                -- ldoc allows comments in the formal arg list to be used
                comments:append (fargs.comments[name] or pcomments[i] or '')
             end
-            if #pnames > #fargs and fargs[#fargs] ~= '...' then
+            -- A formal argument of ... may match any number of params, however.
+            if #pnames > #fargs then
                for i = #fargs+1,#pnames do
-                  self:warning("extra param with no formal argument: "..pnames[i])
+                  if not varargs then
+                     self:warning("extra param with no formal argument: "..quote(pnames[i]))
+                  else
+                     names:append(pnames[i])
+                     comments:append(pcomments[i] or '')
+                  end
                end
             end
          end
diff --git a/tests/example/config.ld b/tests/example/config.ld
index 333198d..f0d8a38 100644
--- a/tests/example/config.ld
+++ b/tests/example/config.ld
@@ -8,5 +8,7 @@ This description applies to the project as a whole.
 
 alias("p","param")
 
+file = {'mod1.lua','modtest.lua','mylib.c'}
+
 new_type("macro","Macros")
 
diff --git a/tests/example/mod1.lua b/tests/example/mod1.lua
index 9ba0b21..5475818 100644
--- a/tests/example/mod1.lua
+++ b/tests/example/mod1.lua
@@ -57,4 +57,25 @@ function mod1.zero_function(p)
 end
 
 
+-------
+-- Multiple params may match a varargs function.
+-- Generally, ldoc tries to be strict about matching params and formal arguments,
+-- but this is relaxed for varargs: `function other(p,...)`
+-- @param p
+-- @param q
+-- @param r
+function mod1.other(p,...)
+-- something cunning with select(2,...)
+end
 
+-------
+-- A function with typed arguments.
+-- The tparam tag is followed by the 'type'. There is no standard way
+-- to represent Lua types, but you can adopt a convention. Type names
+-- will be resolved. treturn must include a description after the type.
+-- @tparam string name
+-- @tparam number age
+-- @treturn string modified age
+function mod1.typed(name,age)
+
+end
diff --git a/tests/example/modtest.lua b/tests/example/modtest.lua
index e59adc0..cefabf1 100644
--- a/tests/example/modtest.lua
+++ b/tests/example/modtest.lua
@@ -3,7 +3,16 @@
 -- Scripts are not containers in the sense that modules are,
 -- (although perhaps the idea of 'commands' could be adopted for some utilities)
 -- It allows any upfront script comments to be included in the
--- documentation.
+-- documentation. Any long string marked with the 'usage' tag will also appear
+-- in this area.
+--
 -- @script modtest
 
-print 'hello, world'
+--- @usage
+local usage = [[
+modtest NAME
+where NAME is your favourite name!
+
+]]
+
+print ('hello',arg[1])