From a825a316a17cf1b8c579ba3b7609b61dcf1183e5 Mon Sep 17 00:00:00 2001 From: Steve Donovan Date: Mon, 26 Aug 2013 13:37:41 +0200 Subject: [PATCH] error tag now auto-groups; refactorings --- ldoc/doc.lua | 85 +++++++++++++++++++++++++++------------ ldoc/parse.lua | 17 +++++--- tests/styles/multiple.lua | 4 +- 3 files changed, 73 insertions(+), 33 deletions(-) diff --git a/ldoc/doc.lua b/ldoc/doc.lua index d875767..32e902b 100644 --- a/ldoc/doc.lua +++ b/ldoc/doc.lua @@ -492,7 +492,7 @@ function Item.check_tag(tags,tag, value, modifiers) modifiers[m] = v end end - else -- has to be a function + else -- has to be a function that at least returns tag, value return alias(tags,value,modifiers) end end @@ -545,6 +545,13 @@ end local build_arg_list, split_iden -- forward declaration +function Item:split_param (line) + local name, comment = line:match('%s*([%w_%.:]+)(.*)') + if not name then + self:error("bad param name format '"..line.."'. Are you missing a parameter name?") + end + return name, comment +end function Item:finish() local tags = self.tags @@ -593,10 +600,7 @@ function Item:finish() local param_names, comments = List(), List() if params then for line in params:iter() do - local name, comment = line:match('%s*([%w_%.:]+)(.*)') - if not name then - self:error("bad param name format '"..line.."'. Are you missing a parameter name?") - end + local name, comment = self:split_param(line) param_names:append(name) comments:append(comment) end @@ -612,16 +616,10 @@ function Item:finish() if fargs then if #param_names == 0 then --docs may be embedded in argument comments; in either case, use formal arg names - formal = List() - if fargs.return_comment then - local retc = self:parse_argument_comment(fargs.return_comment,'return') - self.ret = List{retc} - end - for i, name in ipairs(fargs) do - formal:append(name) - comments:append(self:parse_argument_comment(fargs.comments[name],self.parameter)) - end - elseif #fargs > 0 then + local ret + formal,comments,ret = self:parse_formal_arguments(fargs) + if ret and not self.ret then self.ret = ret end + elseif #fargs > 0 then -- consistency check! local varargs = fargs[#fargs] == '...' if varargs then table.remove(fargs) end local k = 0 @@ -639,14 +637,12 @@ function Item:finish() end end if k < #fargs then - for i = k+1,#fargs do - if fargs[i] ~= '...' then - self:warning("undocumented formal argument: "..quote(fargs[i])) - end - end + for i = k+1,#fargs do if fargs[i] ~= '...' then + self:warning("undocumented formal argument: "..quote(fargs[i])) + end end end - end - end + end -- #fargs > 0 + end -- fargs -- the comments are associated with each parameter by -- adding name-value pairs to the params list (this is @@ -702,6 +698,19 @@ function Item:parse_argument_comment (comment,field) return comment or '' end +function Item:parse_formal_arguments (fargs) + local formal, comments, ret = List(), List() + if fargs.return_comment then + local retc = self:parse_argument_comment(fargs.return_comment,'return') + ret = List{retc} + end + for i, name in ipairs(fargs) do + formal:append(name) + comments:append(self:parse_argument_comment(fargs.comments[name],self.parameter)) + end + return formal, comments, ret +end + function split_iden (name) if name == '...' then return name end local pname,field = name:match('(.-)%.(.+)') @@ -753,6 +762,9 @@ function build_arg_list (names,pmods) return '('..table.concat(buffer)..')' end +------ retrieving information about parameters ----- +-- The template leans on these guys heavily.... + function Item:param_modifiers (p) local mods = self.modifiers[self.parameter] if not mods then return '' end @@ -798,7 +810,7 @@ function Item:type_of_ret(idx) end local function integer_keys(t) - if not t then return 0 end + if type(t) ~= 'table' then return 0 end for k in pairs(t) do local num = tonumber(k) if num then return num end @@ -832,7 +844,7 @@ function Item:build_return_groups() if fields then local fcomments = List() for i,f in ipairs(fields) do - local name, comment = f:match('%s*([%w_%.:]+)(.*)') + local name, comment = self:split_param(f) fields[i] = name fcomments[i] = coment end @@ -852,12 +864,33 @@ end -- this alias macro implements @error. -- Alias macros need to return the same results as Item:check_tags... function doc.error_macro(tags,value,modifiers) + local g = '2' -- our default group id + -- Were we given an explicit group modifier? local key = integer_keys(modifiers) - local g = key > 0 and tostring(key) or '2' + if key > 0 then + g = tostring(key) + else + local l = tags:get 'return' + if l then -- there were returns already...... + -- maximum group of _existing_ error return + local grp, text = 0, List() + for r in l:iter() do if type(r) == 'table' then + grp = math.max(grp,r.modifiers._err or 0) + text:append(r[1]) + end end + if grp > 0 then -- cool, create new group + g = tostring(grp+1) + text:append(value) + print(text) + end + end + end tags:add('return','',{[g]=true,type='nil'}) - return 'return', value, {[g]=true,type='string'} + -- note that this 'return' is tagged with _err! + return 'return', value, {[g]=true,_err=tonumber(g),type='string'} end +---------- bothering the user -------------------- function Item:warning(msg) local file = self.file and self.file.filename diff --git a/ldoc/parse.lua b/ldoc/parse.lua index 671f2ca..6889dfe 100644 --- a/ldoc/parse.lua +++ b/ldoc/parse.lua @@ -96,11 +96,8 @@ function Tags:add (tag,value,modifiers) if modifiers then -- how modifiers are encoded value = {value,modifiers=modifiers} end - local ovalue = rawget(self,tag) - if ovalue then -- previous value? - if getmetatable(ovalue) ~= List then - ovalue = List{ovalue} - end + local ovalue = self:get(tag) + if ovalue then ovalue:append(value) value = ovalue end @@ -110,6 +107,16 @@ function Tags:add (tag,value,modifiers) end end +function Tags:get (tag) + local ovalue = rawget(self,tag) + if ovalue then -- previous value? + if getmetatable(ovalue) ~= List then + ovalue = List{ovalue} + end + return ovalue + end +end + function Tags:iter () return self._order:iter() end diff --git a/tests/styles/multiple.lua b/tests/styles/multiple.lua index 4800a94..355d788 100644 --- a/tests/styles/multiple.lua +++ b/tests/styles/multiple.lua @@ -18,8 +18,8 @@ function mul2 () end ----- -- function with multiple error tags -- @return result --- @error[1] not found --- @error[2] bad format +-- @error not found +-- @error bad format function mul3 () end -----