From 4de863ca2d4e0e28a6a8f6819396c3bd0824b52f Mon Sep 17 00:00:00 2001 From: Geoff Leyland Date: Mon, 29 Oct 2012 13:14:03 +1300 Subject: [PATCH 1/6] added a makefile to make installing a little simpler --- makefile | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 makefile diff --git a/makefile b/makefile new file mode 100644 index 0000000..a0ff1b0 --- /dev/null +++ b/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 From 53166f626f319c223416bdebac91c6a1e06cba19 Mon Sep 17 00:00:00 2001 From: Geoff Leyland Date: Mon, 29 Oct 2012 13:14:54 +1300 Subject: [PATCH 2/6] Added a comple of missing requires --- ldoc.lua | 1 + ldoc/tools.lua | 1 + 2 files changed, 2 insertions(+) diff --git a/ldoc.lua b/ldoc.lua index 115755c..8d39d12 100644 --- a/ldoc.lua +++ b/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' diff --git a/ldoc/tools.lua b/ldoc/tools.lua index e197b13..10a2a6b 100644 --- a/ldoc/tools.lua +++ b/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 From a2a3da455e2188b81d8d9dc40a381b9eeaa81fde Mon Sep 17 00:00:00 2001 From: Geoff Leyland Date: Mon, 29 Oct 2012 13:17:44 +1300 Subject: [PATCH 3/6] Remove requirement to have more than one formal argument when using comments on the arguments. I'm not sure what that was for, so I might have broken something --- ldoc/doc.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ldoc/doc.lua b/ldoc/doc.lua index 489c215..3bf6471 100644 --- a/ldoc/doc.lua +++ b/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] == '...' From 90e87ece0c2e44b7e0bc06bf09ef9272f4e80c30 Mon Sep 17 00:00:00 2001 From: Geoff Leyland Date: Mon, 29 Oct 2012 13:22:52 +1300 Subject: [PATCH 4/6] Handle multi-line argument descriptions embedded in (and after) a function's formal parameters --- ldoc/tools.lua | 46 +++++++++++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/ldoc/tools.lua b/ldoc/tools.lua index 10a2a6b..bbb42e6 100644 --- a/ldoc/tools.lua +++ b/ldoc/tools.lua @@ -280,37 +280,49 @@ function M.get_parameters (tok,endtoken,delim) local function set_comment (idx,tok) local text = value_of(tok):gsub('%s*$','') - args.comments[args[idx]] = text + 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 - if i > 1 then set_comment(i-1,tl[1]) end - if #tl > 1 then - args:append(value_of(tl[2])) + for j = 1, #tl - 1 do + if type_of(tl[j]) ~= "comment" then + return nil, "Couldn't parse function arguments" + end + set_comment(i-1,tl[j]) end - else - args:append(value_of(tl[1])) - end - if i == #ltl then - local last_tok = tl[#tl] - if #tl > 1 and type_of(last_tok) == 'comment' then - set_comment(i,last_tok) + 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 + set_comment(i,last_tok) + end end - end 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 - local t = {tok()} - if type_of(t) == 'comment' then - set_comment(n,t) + while true do + local t = {tok()} + if type_of(t) == 'comment' then + set_comment(n,t) + else + break + end end end end From 9924e4dced646cf306b3574b916ed7d96935956d Mon Sep 17 00:00:00 2001 From: Geoff Leyland Date: Mon, 29 Oct 2012 13:24:49 +1300 Subject: [PATCH 5/6] Parse type expressions like '?table|string' and turn them into 'optional table or string' --- ldoc/html.lua | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/ldoc/html.lua b/ldoc/html.lua index 3e00def..f671ad8 100644 --- a/ldoc/html.lua +++ b/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 - return (tp:gsub('%a[%w_%.]*',function(name) + if not tp or tp == '' then return '' end + 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 ('%s '):format(ldoc.href(ref),name) + types[#types+1] = ('%s '):format(ldoc.href(ref),name) else - return ''..name..' ' + types[#types+1] = ''..name..' ' 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)) From 2b304a2252f4f5b820afc2619e0a492276bd8da0 Mon Sep 17 00:00:00 2001 From: Geoff Leyland Date: Mon, 29 Oct 2012 13:26:07 +1300 Subject: [PATCH 6/6] Use classes for formatting argument descriptions rather than tags --- ldoc/html.lua | 4 ++-- ldoc/html/ldoc_css.lua | 5 +++++ ldoc/html/ldoc_ltp.lua | 12 ++++++++++-- 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/ldoc/html.lua b/ldoc/html.lua index f671ad8..05c77fa 100644 --- a/ldoc/html.lua +++ b/ldoc/html.lua @@ -109,9 +109,9 @@ function html.generate_output(ldoc, args, project) for name in tp:gmatch("[^|]+") do local ref,err = markup.process_reference(name) if ref then - types[#types+1] = ('%s '):format(ldoc.href(ref),name) + types[#types+1] = ('%s'):format(ldoc.href(ref),name) else - types[#types+1] = ''..name..' ' + types[#types+1] = ''..name..'' end end local names = table.concat(types, ", ", 1, math.max(#types-1, 1)) diff --git a/ldoc/html/ldoc_css.lua b/ldoc/html/ldoc_css.lua index e706f85..9e3ad9c 100644 --- a/ldoc/html/ldoc_css.lua +++ b/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;} diff --git a/ldoc/html/ldoc_ltp.lua b/ldoc/html/ldoc_ltp.lua index 7e7e1db..cf1e2eb 100644 --- a/ldoc/html/ldoc_ltp.lua +++ b/ldoc/html/ldoc_ltp.lua @@ -140,8 +140,12 @@ return [==[

$(module.kinds:type_of(item).subnames):

    # for p in iter(item.params) do +
  • $(p) # local tp = ldoc.typename(item:type_of_param(p)) -
  • $(p): $(tp)$(M(item.params[p],item))
    • +# if tp ~= '' then + $(tp) +# end + $(M(item.params[p],item)) # end -- for
# end -- if params @@ -161,8 +165,12 @@ return [==[

Returns:

    # 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 + $(tp) +# end + $(M(r,item))$(il) # end -- for
# end -- if returns