Merge pull request #26 from geoffleyland/master

Missing requires; makefile; parameter descriptions; html

ldoc.lua

@@ -19,6 +19,7 @@
 local class = require 'pl.class'
 local app = require 'pl.app'
 local path = require 'pl.path'
+local dir = require 'pl.dir'
 local utils = require 'pl.utils'
 local List = require 'pl.List'
 local stringx = require 'pl.stringx'

ldoc/doc.lua

@@ -432,7 +432,7 @@ function Item:finish()
       -- if available as the authoritative list, and warn if there's an inconsistency.
       if self.formal_args then
          local fargs = self.formal_args
-         if #fargs ~= 1 then
+         if #fargs ~= 0 then
             local pnames, pcomments = names, comments
             names, comments = List(),List()
             local varargs = fargs[#fargs] == '...'

ldoc/html.lua

@@ -98,15 +98,32 @@ function html.generate_output(ldoc, args, project)
    end
 
    function ldoc.typename (tp)
-      if not tp then return '' end
+      if not tp or tp == '' then return '' end
-      return (tp:gsub('%a[%w_%.]*',function(name)
+      local optional
+      local tp2 = tp:match("%?|?(.*)")
+      if tp2 then
+         optional = true
+         tp = tp2
+      end
+      local types = {}
+      for name in tp:gmatch("[^|]+") do
          local ref,err = markup.process_reference(name)
          if ref then
-            return ('<a href="%s">%s</a> '):format(ldoc.href(ref),name)
+            types[#types+1] = ('<a class="type" href="%s">%s</a>'):format(ldoc.href(ref),name)
          else
-            return '<strong>'..name..'</strong> '
+            types[#types+1] = '<span class="type">'..name..'</span>'
          end
-      end))
+      end
+      local names = table.concat(types, ", ", 1, math.max(#types-1, 1))
+      if #types > 1 then names = names.." or "..types[#types] end
+      if optional then
+        if names ~= '' then
+          names = "optional "..names
+        else
+          names = "optional"
+        end
+      end
+      return names
    end
 
    local module_template,err = utils.readfile (path.join(args.template,ldoc.templ))

ldoc/html/ldoc_css.lua

@@ -73,6 +73,11 @@ body {
 }
 
 code, tt { font-family: monospace; }
+span.parameter { font-family:monospace; }
+span.parameter:after { content:":"; }
+span.types:before { content:"("; }
+span.types:after { content:")"; }
+.type { font-weight: bold; font-style:italic }
 
 body, p, td, th { font-size: .95em; line-height: 1.2em;}
 

ldoc/html/ldoc_ltp.lua

@@ -140,8 +140,12 @@ return [==[
     <h3>$(module.kinds:type_of(item).subnames):</h3>
     <ul>
 #   for p in iter(item.params) do
+      <li><span class="parameter">$(p)</span>
 #     local tp = ldoc.typename(item:type_of_param(p))
-       <li><code><em>$(p)</em></code>: $(tp)$(M(item.params[p],item))</li>
+#     if tp ~= '' then
+        <span class="types">$(tp)</span>
+#     end
+      $(M(item.params[p],item))</li>
 #   end -- for
     </ul>
 #   end -- if params
@@ -161,8 +165,12 @@ return [==[
     <h3>Returns:</h3>
     <ol>
 #     for i,r in ldoc.ipairs(item.ret) do
+        $(li)
 #       local tp = ldoc.typename(item:type_of_ret(i))
-        $(li)$(tp)$(M(r,item))$(il)
+#       if tp ~= '' then
+          <span class="types">$(tp)</span>
+#       end
+        $(M(r,item))$(il)
 #     end -- for
     </ol>
 #   end -- if returns

ldoc/tools.lua

@@ -6,6 +6,7 @@ local class = require 'pl.class'
 local List = require 'pl.List'
 local path = require 'pl.path'
 local utils = require 'pl.utils'
+local tablex = require 'pl.tablex'
 local tools = {}
 local M = tools
 local append = table.insert
@@ -279,21 +280,29 @@ function M.get_parameters (tok,endtoken,delim)
 
    local function set_comment (idx,tok)
       local text = value_of(tok):gsub('%s*$','')
+      local current_comment = args.comments[args[idx]]
+      if current_comment then
+        text = text:match("%s*%-%-+%s*(.*)")
+        args.comments[args[idx]] = current_comment .. " " .. text
+      else
         args.comments[args[idx]] = text
       end
+   end
 
    for i = 1,#ltl do
       --print('check',i,ltl[i],#ltl[i])
       local tl = ltl[i]
       if #tl > 0 then
-      if type_of(tl[1]) == 'comment' then
+         for j = 1, #tl - 1 do
-         if i > 1 then set_comment(i-1,tl[1]) end
+            if type_of(tl[j]) ~= "comment" then
-         if #tl > 1 then
+               return nil, "Couldn't parse function arguments"
-            args:append(value_of(tl[2]))
             end
-      else
+            set_comment(i-1,tl[j])
-         args:append(value_of(tl[1]))
          end
+         if type_of(tl[#tl]) ~= "iden" and type_of(tl[#tl]) ~= "..." then
+            return nil, "Couldn't parse function arguments"
+         end
+         args:append(value_of(tl[#tl]))
          if i == #ltl then
             local last_tok = tl[#tl]
             if #tl > 1 and type_of(last_tok) == 'comment' then
@@ -303,13 +312,17 @@ function M.get_parameters (tok,endtoken,delim)
       end
    end
 
-   if next(args.comments) then -- we had argument comments
+   if #args == 1 or 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
+         while true do
             local t = {tok()}
             if type_of(t) == 'comment' then
                set_comment(n,t)
+            else
+               break
+            end
          end
       end
    end

makefile

@@ -0,0 +1,24 @@
+LUA= $(shell echo `which lua`)
+LUA_BINDIR= $(shell echo `dirname $(LUA)`)
+LUA_PREFIX= $(shell echo `dirname $(LUA_BINDIR)`)
+LUA_SHAREDIR=$(LUA_PREFIX)/share/lua/5.1
+
+ldoc:
+
+install: install_parts
+	echo "lua $(LUA_SHAREDIR)/ldoc.lua \$$*" > $(LUA_BINDIR)/ldoc
+	chmod +x $(LUA_BINDIR)/ldoc
+
+install_luajit: install_parts
+	echo "luajit $(LUA_SHAREDIR)/ldoc.lua \$$*" > $(LUA_BINDIR)/ldoc
+	chmod +x $(LUA_BINDIR)/ldoc
+
+install_parts:
+	mkdir -p $(LUA_SHAREDIR)
+	cp ldoc.lua $(LUA_SHAREDIR)
+	cp -r ldoc $(LUA_SHAREDIR)
+
+uninstall: 
+	-rm $(LUA_SHAREDIR)/ldoc.lua
+	-rm -r $(LUA_SHAREDIR)/ldoc
+	-rm $(LUA_BINDIR)/ldoc