- comments within formal arguments: last comment may be outside the

closing parenthesis. If comments are of form TYPE:COMMENT then
equivalent to @tparam not @param. See tests/factory/mymod.lua
- @constructor tag attaches CLASS. as prefix to name
- No more implicit use of "require 'pl'".

ldoc.lua

@@ -16,7 +16,14 @@
 -- @license MIT/X11
 -- @script ldoc
 
-require 'pl'
+local class = require 'pl.class'
+local app = require 'pl.app'
+local path = require 'pl.path'
+local utils = require 'pl.utils'
+local List = require 'pl.List'
+local stringx = require 'pl.stringx'
+local tablex = require 'pl.tablex'
+
 
 local append = table.insert
 

ldoc/doc.lua

@@ -2,7 +2,9 @@
 -- Defining the ldoc document model.
 
 
-require 'pl'
+local class = require 'pl.class'
+local utils = require 'pl.utils'
+local List = require 'pl.List'
 
 local doc = {}
 local global = require 'ldoc.builtin.globals'
@@ -222,9 +224,8 @@ function File:finish()
                -- if it was a class, then the name should be 'Class:foo'
                local stype = this_mod.section.type
                if doc.class_tag(stype) then
-                  local prefix = this_mod.section.name .. ':'
-                  local i1,i2 = item.name:find(prefix)
-                  if not has_prefix(item.name,prefix) and not item.tags.constructor then
+                  local prefix = this_mod.section.name .. (not item.tags.constructor and ':' or '.')
+                  if not has_prefix(item.name,prefix) then
                      item.name =  prefix .. item.name
                   end
                   if stype == 'factory'  then
@@ -416,8 +417,9 @@ function Item:finish()
       else
          self.parameter = 'field'
       end
-      local params = read_del(tags,self.parameter)
-      local names, comments, modifiers = List(), List(), List()
+      local field = self.parameter
+      local params = read_del(tags,field)
+      local names, comments = List(), List()
       if params then
          for line in params:iter() do
             local name, comment = line :match('%s*([%w_%.:]+)(.*)')
@@ -447,8 +449,23 @@ function Item:finish()
                   end
                end
                names:append(name)
-               -- ldoc allows comments in the formal arg list to be used
-               comments:append (fargs.comments[name] or pcomments[i] or '')
+               local comment = pcomments[i]
+               if not comment then
+                  -- ldoc allows comments in the formal arg list to be used, if they aren't specified with @param
+                  -- Further, these comments may start with a type followed by a colon, and are then equivalent
+                  -- to a @tparam
+                  comment = fargs.comments[name]
+                  if comment then
+                     comment = comment:gsub('^%-+%s*','')
+                     local type,rest = comment:match '([^:]+):(.*)'
+                     if type then
+                        if not self.modifiers[field] then self.modifiers[field] = List() end
+                        self.modifiers[field]:append {type = type}
+                        comment = rest
+                     end
+                  end
+               end
+               comments:append (comment or '')
             end
             -- A formal argument of ... may match any number of params, however.
             if #pnames > #fargs then
@@ -468,7 +485,7 @@ function Item:finish()
       -- adding name-value pairs to the params list (this is
       -- also done for any associated modifiers)
       self.params = names
-      local pmods = self.modifiers[self.parameter]
+      local pmods = self.modifiers[field]
       for i,name in ipairs(self.params) do
          self.params[name] = comments[i]
          if pmods then
@@ -543,9 +560,7 @@ end
 local err = io.stderr
 
 local function custom_see_references (s)
-    --err:write('next',next(see_reference_handlers),'\n')
     for pat, action in pairs(see_reference_handlers) do
-        --err:write('pair ',pair,'\n')
         if s:match(pat) then
             local label, href = action(s:match(pat))
             return {href = href, label = label}

ldoc/html.lua

@@ -13,6 +13,10 @@
 -- generalizes the idea of these project-level categories and in fact custom categories
 -- can be created (refered to as 'kinds' in the code)
 
+local List = require 'pl.List'
+local utils = require 'pl.utils'
+local path = require 'pl.path'
+local stringx = require 'pl.stringx'
 local template = require 'pl.template'
 local tools = require 'ldoc.tools'
 local markup = require 'ldoc.markup'

ldoc/lang.lua

@@ -3,8 +3,8 @@
 -- This encapsulates the different strategies needed for parsing C and Lua
 -- source code.
 
-require 'pl'
-
+local class = require 'pl.class'
+local utils = require 'pl.utils'
 local tools = require 'ldoc.tools'
 local lexer = require 'ldoc.lexer'
 

ldoc/markup.lua

@@ -3,9 +3,9 @@
 -- Currently just does Markdown, but this is intended to
 -- be the general module for managing other formats as well.
 
-require 'pl'
 local doc = require 'ldoc.doc'
 local utils = require 'pl.utils'
+local stringx = require 'pl.stringx'
 local prettify = require 'ldoc.prettify'
 local quit, concat, lstrip = utils.quit, table.concat, stringx.lstrip
 local markup = {}

ldoc/parse.lua

@@ -1,6 +1,8 @@
 -- parsing code for doc comments
 
-require 'pl'
+local List = require 'pl.List'
+local Map = require 'pl.Map'
+local stringio = require 'pl.stringio'
 local lexer = require 'ldoc.lexer'
 local tools = require 'ldoc.tools'
 local doc = require 'ldoc.doc'

ldoc/prettify.lua

@@ -3,7 +3,7 @@
 -- for known modules and functions.
 -- A module reference to an example `test-fun.lua` would look like
 -- `@{example:test-fun}`.
-require 'pl'
+local List = require 'pl.List'
 local lexer = require 'ldoc.lexer'
 local globals = require 'ldoc.builtin.globals'
 local tnext = lexer.skipws

ldoc/tools.lua

@@ -2,7 +2,10 @@
 -- General utility functions for ldoc
 -- @module tools
 
-require 'pl'
+local class = require 'pl.class'
+local List = require 'pl.List'
+local path = require 'pl.path'
+local utils = require 'pl.utils'
 local tools = {}
 local M = tools
 local append = table.insert
@@ -300,6 +303,17 @@ function M.get_parameters (tok,endtoken,delim)
       end
    end
 
+   if next(args.comments) then -- we had argument comments
+      -- but the last one may be outside the parens! (Geoff style)
+      local n = #args
+      if not args.comments[n] then
+         local t = {tok()}
+         if type_of(t) == 'comment' then
+            set_comment(n,t)
+         end
+      end
+   end
+
    return args
 end
 

tests/factory/mymod.lua

@@ -0,0 +1,21 @@
+--- mymod
+
+local mymod = {}
+
+--- everything!
+function mymod.query (
+    a, --string: first arg
+    b, --int: second arg
+    c  --table: arg
+)
+end
+
+
+--- for everything.
+function mymod.answer (
+    a, -- first arg
+    b, -- second arg
+    c)  -- third arg
+end
+
+return mymod