| 491 | 491 |
modifiers[m] = v
|
| 492 | 492 |
end
|
| 493 | 493 |
end
|
| 494 | |
else -- has to be a function
|
|
494 |
else -- has to be a function that at least returns tag, value
|
| 495 | 495 |
return alias(tags,value,modifiers)
|
| 496 | 496 |
end
|
| 497 | 497 |
end
|
|
| 544 | 544 |
|
| 545 | 545 |
local build_arg_list, split_iden -- forward declaration
|
| 546 | 546 |
|
|
547 |
function Item:split_param (line)
|
|
548 |
local name, comment = line:match('%s*([%w_%.:]+)(.*)')
|
|
549 |
if not name then
|
|
550 |
self:error("bad param name format '"..line.."'. Are you missing a parameter name?")
|
|
551 |
end
|
|
552 |
return name, comment
|
|
553 |
end
|
| 547 | 554 |
|
| 548 | 555 |
function Item:finish()
|
| 549 | 556 |
local tags = self.tags
|
|
| 592 | 599 |
local param_names, comments = List(), List()
|
| 593 | 600 |
if params then
|
| 594 | 601 |
for line in params:iter() do
|
| 595 | |
local name, comment = line:match('%s*([%w_%.:]+)(.*)')
|
| 596 | |
if not name then
|
| 597 | |
self:error("bad param name format '"..line.."'. Are you missing a parameter name?")
|
| 598 | |
end
|
|
602 |
local name, comment = self:split_param(line)
|
| 599 | 603 |
param_names:append(name)
|
| 600 | 604 |
comments:append(comment)
|
| 601 | 605 |
end
|
|
| 611 | 615 |
if fargs then
|
| 612 | 616 |
if #param_names == 0 then
|
| 613 | 617 |
--docs may be embedded in argument comments; in either case, use formal arg names
|
| 614 | |
formal = List()
|
| 615 | |
if fargs.return_comment then
|
| 616 | |
local retc = self:parse_argument_comment(fargs.return_comment,'return')
|
| 617 | |
self.ret = List{retc}
|
| 618 | |
end
|
| 619 | |
for i, name in ipairs(fargs) do
|
| 620 | |
formal:append(name)
|
| 621 | |
comments:append(self:parse_argument_comment(fargs.comments[name],self.parameter))
|
| 622 | |
end
|
| 623 | |
elseif #fargs > 0 then
|
|
618 |
local ret
|
|
619 |
formal,comments,ret = self:parse_formal_arguments(fargs)
|
|
620 |
if ret and not self.ret then self.ret = ret end
|
|
621 |
elseif #fargs > 0 then -- consistency check!
|
| 624 | 622 |
local varargs = fargs[#fargs] == '...'
|
| 625 | 623 |
if varargs then table.remove(fargs) end
|
| 626 | 624 |
local k = 0
|
|
| 638 | 636 |
end
|
| 639 | 637 |
end
|
| 640 | 638 |
if k < #fargs then
|
| 641 | |
for i = k+1,#fargs do
|
| 642 | |
if fargs[i] ~= '...' then
|
| 643 | |
self:warning("undocumented formal argument: "..quote(fargs[i]))
|
| 644 | |
end
|
| 645 | |
end
|
| 646 | |
end
|
| 647 | |
end
|
| 648 | |
end
|
|
639 |
for i = k+1,#fargs do if fargs[i] ~= '...' then
|
|
640 |
self:warning("undocumented formal argument: "..quote(fargs[i]))
|
|
641 |
end end
|
|
642 |
end
|
|
643 |
end -- #fargs > 0
|
|
644 |
end -- fargs
|
| 649 | 645 |
|
| 650 | 646 |
-- the comments are associated with each parameter by
|
| 651 | 647 |
-- adding name-value pairs to the params list (this is
|
|
| 699 | 695 |
end
|
| 700 | 696 |
end
|
| 701 | 697 |
return comment or ''
|
|
698 |
end
|
|
699 |
|
|
700 |
function Item:parse_formal_arguments (fargs)
|
|
701 |
local formal, comments, ret = List(), List()
|
|
702 |
if fargs.return_comment then
|
|
703 |
local retc = self:parse_argument_comment(fargs.return_comment,'return')
|
|
704 |
ret = List{retc}
|
|
705 |
end
|
|
706 |
for i, name in ipairs(fargs) do
|
|
707 |
formal:append(name)
|
|
708 |
comments:append(self:parse_argument_comment(fargs.comments[name],self.parameter))
|
|
709 |
end
|
|
710 |
return formal, comments, ret
|
| 702 | 711 |
end
|
| 703 | 712 |
|
| 704 | 713 |
function split_iden (name)
|
|
| 752 | 761 |
return '('..table.concat(buffer)..')'
|
| 753 | 762 |
end
|
| 754 | 763 |
|
|
764 |
------ retrieving information about parameters -----
|
|
765 |
-- The template leans on these guys heavily....
|
|
766 |
|
| 755 | 767 |
function Item:param_modifiers (p)
|
| 756 | 768 |
local mods = self.modifiers[self.parameter]
|
| 757 | 769 |
if not mods then return '' end
|
|
| 797 | 809 |
end
|
| 798 | 810 |
|
| 799 | 811 |
local function integer_keys(t)
|
| 800 | |
if not t then return 0 end
|
|
812 |
if type(t) ~= 'table' then return 0 end
|
| 801 | 813 |
for k in pairs(t) do
|
| 802 | 814 |
local num = tonumber(k)
|
| 803 | 815 |
if num then return num end
|
|
| 831 | 843 |
if fields then
|
| 832 | 844 |
local fcomments = List()
|
| 833 | 845 |
for i,f in ipairs(fields) do
|
| 834 | |
local name, comment = f:match('%s*([%w_%.:]+)(.*)')
|
|
846 |
local name, comment = self:split_param(f)
|
| 835 | 847 |
fields[i] = name
|
| 836 | 848 |
fcomments[i] = coment
|
| 837 | 849 |
end
|
|
| 851 | 863 |
-- this alias macro implements @error.
|
| 852 | 864 |
-- Alias macros need to return the same results as Item:check_tags...
|
| 853 | 865 |
function doc.error_macro(tags,value,modifiers)
|
|
866 |
local g = '2' -- our default group id
|
|
867 |
-- Were we given an explicit group modifier?
|
| 854 | 868 |
local key = integer_keys(modifiers)
|
| 855 | |
local g = key > 0 and tostring(key) or '2'
|
|
869 |
if key > 0 then
|
|
870 |
g = tostring(key)
|
|
871 |
else
|
|
872 |
local l = tags:get 'return'
|
|
873 |
if l then -- there were returns already......
|
|
874 |
-- maximum group of _existing_ error return
|
|
875 |
local grp, text = 0, List()
|
|
876 |
for r in l:iter() do if type(r) == 'table' then
|
|
877 |
grp = math.max(grp,r.modifiers._err or 0)
|
|
878 |
text:append(r[1])
|
|
879 |
end end
|
|
880 |
if grp > 0 then -- cool, create new group
|
|
881 |
g = tostring(grp+1)
|
|
882 |
text:append(value)
|
|
883 |
print(text)
|
|
884 |
end
|
|
885 |
end
|
|
886 |
end
|
| 856 | 887 |
tags:add('return','',{[g]=true,type='nil'})
|
| 857 | |
return 'return', value, {[g]=true,type='string'}
|
| 858 | |
end
|
| 859 | |
|
|
888 |
-- note that this 'return' is tagged with _err!
|
|
889 |
return 'return', value, {[g]=true,_err=tonumber(g),type='string'}
|
|
890 |
end
|
|
891 |
|
|
892 |
---------- bothering the user --------------------
|
| 860 | 893 |
|
| 861 | 894 |
function Item:warning(msg)
|
| 862 | 895 |
local file = self.file and self.file.filename
|