Codebase list lua-ldoc / df72613
structure return needs 'typename'; by default merge_error_groups will combine different error tag texts Steve Donovan 10 years ago
5 changed file(s) with 68 addition(s) and 21 deletion(s). Raw diff Collapse all Expand all
+50
-14
ldoc/doc.lua less more
2020 -- - 'N' tags which have no associated value, like 'local` (TAG_FLAG)
2121 -- - 'T' tags which represent a type, like 'function' (TAG_TYPE)
2222 local known_tags = {
23 param = 'M', see = 'M', usage = 'ML', ['return'] = 'M', field = 'M', author='M',set='M';
23 param = 'M', see = 'M', comment = 'M', usage = 'ML', ['return'] = 'M', field = 'M', author='M',set='M';
2424 class = 'id', name = 'id', pragma = 'id', alias = 'id', within = 'id',
2525 copyright = 'S', summary = 'S', description = 'S', release = 'S', license = 'S',
2626 fixme = 'S', todo = 'S', warning = 'S', raise = 'S', charset = 'S',
129129
130130 function doc.expand_annotation_item (tags, last_item)
131131 if tags.summary ~= '' then return false end
132 local item_name = last_item and last_item.tags.name or '?'
132133 for tag, value in pairs(tags) do
133134 if known_tags._annotation_tags[tag] then
134135 tags:add('class','annotation')
135136 tags:add('summary',value)
136 local item_name = last_item and last_item.tags.name or '?'
137137 tags:add('name',item_name..'-'..tag..acount)
138138 acount = acount + 1
139139 return true
434434
435435 if ttype == TAG_MULTI or ttype == TAG_MULTI_LINE then -- value is always a List!
436436 local ovalue = self.tags[tag]
437 if is_list(ovalue) then
438 ovalue:append(value)
437 if ovalue then -- already defined, must be a list
438 --print(tag,ovalue,value)
439 if is_list(value) then
440 ovalue:extend(value)
441 else
442 ovalue:append(value)
443 end
439444 value = ovalue
440445 end
446 -- these multiple values are always represented as lists
441447 if not is_list(value) then
442448 value = List{value}
443449 end
834840 return r.type, r.ctypes
835841 end
836842
843 local struct_return_type = '*'
844
837845 function Item:build_return_groups()
838846 local modifiers = self.modifiers
839847 local retmod = modifiers['return']
848856 groups:append(group)
849857 lastg = g
850858 end
859 --require 'pl.pretty'.dump(ret)
851860 group:append({text=ret, type = mods.type or '',mods = mods})
852861 end
853862 -- order by groups to force error groups to the end
854863 table.sort(groups,function(g1,g2) return g1.g < g2.g end)
855864 self.retgroups = groups
865 --require 'pl.pretty'.dump(groups)
856866 -- cool, now see if there are any treturns that have tfields to associate with
857867 local fields = self.tags.field
858868 if fields then
860870 for i,f in ipairs(fields) do
861871 local name, comment = self:split_param(f)
862872 fields[i] = name
863 fcomments[i] = coment
873 fcomments[i] = comment
864874 end
865875 local fmods = modifiers.field
866876 for group in groups:iter() do for r in group:iter() do
867 if r.mods and r.mods.type == '*' then
868 local ctypes = List()
869 for i,f in ipairs(fields) do
877 if r.mods and r.mods.type then
878 local ctypes, T = List(), r.mods.type
879 for i,f in ipairs(fields) do if fmods[i][T] then
870880 ctypes:append {name=f,type=fmods[i].type,comment=fcomments[i]}
871 end
881 end end
872882 r.ctypes = ctypes
883 --require 'pl.pretty'.dump(ctypes)
873884 end
874885 end end
875886 end
876887 end
888
889 local ecount = 0
877890
878891 -- this alias macro implements @error.
879892 -- Alias macros need to return the same results as Item:check_tags...
880893 function doc.error_macro(tags,value,modifiers)
894 local merge_groups = doc.ldoc.merge_error_groups
881895 local g = '2' -- our default group id
882896 -- Were we given an explicit group modifier?
883897 local key = integer_keys(modifiers)
887901 local l = tags:get 'return'
888902 if l then -- there were returns already......
889903 -- maximum group of _existing_ error return
890 local grp, text = 0, List()
904 local grp, lastr = 0
891905 for r in l:iter() do if type(r) == 'table' then
892 grp = math.max(grp,r.modifiers._err or 0)
893 text:append(r[1])
906 local rg = r.modifiers._err
907 if rg then
908 lastr = r
909 grp = math.max(grp,rg)
910 end
894911 end end
895912 if grp > 0 then -- cool, create new group
896 g = tostring(grp+1)
897 text:append(value)
913 if not merge_groups then
914 g = tostring(grp+1)
915 else
916 local mods, text, T = lastr.modifiers
917 local new = function(text)
918 return mods._collected..' '..text,{type='string',[T]=true}
919 end
920 if not mods._collected then
921 text = lastr[1]
922 lastr[1] = merge_groups
923 T = '@'..ecount
924 mods.type = T
925 mods._collected = 1
926 ecount = ecount + 1
927 tags:add('field',new(text))
928 else
929 T = mods.type
930 end
931 mods._collected = mods._collected + 1
932 return 'field',new(value)
933 end
898934 end
899935 end
900936 end
+1
-1
ldoc/html.lua less more
167167 end
168168
169169 function ldoc.typename (tp)
170 if not tp or tp == '' then return '' end
170 if not tp or tp == '' or tp:match '^@' then return '' end
171171 local optional
172172 -- ?<type> is short for ?nil|<type>
173173 if tp:match("^%?") and not tp:match '|' then
+8
-2
ldoc.lua less more
129129 -- the ldoc table represents the API available in `config.ld`.
130130 local ldoc = { charset = 'UTF-8' }
131131 local add_language_extension
132 -- hacky way for doc module to be passed options...
133 doc.ldoc = ldoc
132134
133135 local function override (field)
134136 if ldoc[field] ~= nil then args[field] = ldoc[field] end
192194 'alias','add_language_extension','new_type','add_section', 'tparam_alias',
193195 'file','project','title','package','format','output','dir','ext', 'topics',
194196 'one','style','template','description','examples', 'pretty', 'charset', 'plain',
195 'readme','all','manual_url', 'ignore', 'colon', 'sort', 'module_file',
196 'boilerplate','merge', 'wrap', 'not_luadoc', 'template_escape',
197 'readme','all','manual_url', 'ignore', 'colon', 'sort', 'module_file','vars',
198 'boilerplate','merge', 'wrap', 'not_luadoc', 'template_escape','merge_error_groups',
197199 'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler',
198200 'no_space_before_args',
199201 }
371373 override 'merge'
372374 override 'not_luadoc'
373375 override 'module_file'
376
377 if ldoc.merge_error_groups == nil then
378 ldoc.merge_error_groups = 'Error Message'
379 end
374380
375381 -- ldoc.module_file establishes a partial ordering where the
376382 -- master module files are processed first.
+5
-1
tests/styles/multiple.lua less more
2626 -- @string name
2727 function mul4 (name)
2828 if type(name) ~= 'string' then
29 --- @error not a string
29 --- @error[1] not a string
3030 return nil, 'not a string'
31 end
32 if #name == 0 then
33 --- @error[2] zero-length string
34 return nil, 'zero-length string'
3135 end
3236 --- @treturn string converted to uppercase
3337 return name:upper()
+4
-3
tests/styles/struct.lua less more
44 -----
55 -- returns a 'struct'.
66 -- @string name your name dammit
7 -- @treturn * details of person
8 -- @tfield string name of person
9 -- @tfield int age of person
7 -- @tfield string arb stuff
8 -- @treturn st details of person
9 -- @tfield[st] string name of person
10 -- @tfield[st] int age of person
1011 function struct(name) end
1112