PL utils.unpack compatibility; refactoring error 'tag'
Steve Donovan
10 years ago
| 374 | 374 |
`@set` is a powerful tag which assigns a configuration variable to a value _just for this module_.
|
| 375 | 375 |
Saying `@set no_summary=true` in a module comment will temporarily disable summary generation when
|
| 376 | 376 |
the template is expanded. Generally configuration variables that effect template expansion
|
| 377 | |
are modifiable in this way.
|
|
377 |
are modifiable in this way. For instance, if you wish that the contents of a particular module
|
|
378 |
be sorted, then `@set sort=true` will do it _just_ for that module.
|
| 378 | 379 |
|
| 379 | 380 |
## Sections
|
| 380 | 381 |
|
|
| 829 | 830 |
'see' in that order. (For tables, 'Fields' is used instead of 'Parameters' but internally
|
| 830 | 831 |
fields of a table are stored as the 'param' tag.)
|
| 831 | 832 |
|
|
833 |
By default, the items appear in the order of declaration within their section. If `sort=true`
|
|
834 |
then they will be sorted alphabetically. (This can be set per-module with @{Module_Tags|@set}.)
|
|
835 |
|
| 832 | 836 |
You can of course customize the default template, but there are some parameters that can
|
| 833 | |
control what the template will generate. Setting `one` to `true` in your configuration file
|
|
837 |
control what the template will generate. Setting `one=true` in your configuration file
|
| 834 | 838 |
will give a _one-column_ layout, which can be easier to use as a programming reference. You
|
| 835 | 839 |
can suppress the contents summary with `no_summary`.
|
| 836 | 840 |
|
| 771 | 771 |
return opt
|
| 772 | 772 |
end
|
| 773 | 773 |
|
|
774 |
function Item:subparam(p)
|
|
775 |
local subp = rawget(self.subparams,p)
|
|
776 |
if subp then
|
|
777 |
return subp,p
|
|
778 |
else
|
|
779 |
return {p},nil
|
|
780 |
end
|
|
781 |
end
|
|
782 |
|
|
783 |
function Item:display_name_of(p)
|
|
784 |
local pname,field = split_iden(p)
|
|
785 |
if field then
|
|
786 |
return field
|
|
787 |
else
|
|
788 |
return pname
|
|
789 |
end
|
|
790 |
end
|
|
791 |
|
|
792 |
-------- return values and types -------
|
|
793 |
|
| 774 | 794 |
function Item:type_of_ret(idx)
|
| 775 | 795 |
local rparam = self.modifiers['return'][idx]
|
| 776 | 796 |
return rparam and rparam.type or ''
|
|
| 828 | 848 |
end
|
| 829 | 849 |
end
|
| 830 | 850 |
|
| 831 | |
function Item:subparam(p)
|
| 832 | |
local subp = rawget(self.subparams,p)
|
| 833 | |
if subp then
|
| 834 | |
return subp,p
|
| 835 | |
else
|
| 836 | |
return {p},nil
|
| 837 | |
end
|
| 838 | |
end
|
| 839 | |
|
| 840 | |
function Item:display_name_of(p)
|
| 841 | |
local pname,field = split_iden(p)
|
| 842 | |
if field then
|
| 843 | |
return field
|
| 844 | |
else
|
| 845 | |
return pname
|
| 846 | |
end
|
| 847 | |
end
|
|
851 |
-- this alias macro implements @error.
|
|
852 |
-- Alias macros need to return the same results as Item:check_tags...
|
|
853 |
function doc.error_macro(tags,value,modifiers)
|
|
854 |
local key = integer_keys(modifiers)
|
|
855 |
local g = key > 0 and tostring(key) or '2'
|
|
856 |
tags:add('return','',{[g]=true,type='nil'})
|
|
857 |
return 'return', value, {[g]=true,type='string'}
|
|
858 |
end
|
|
859 |
|
| 848 | 860 |
|
| 849 | 861 |
function Item:warning(msg)
|
| 850 | 862 |
local file = self.file and self.file.filename
|
| 24 | 24 |
local stringx = require 'pl.stringx'
|
| 25 | 25 |
local tablex = require 'pl.tablex'
|
| 26 | 26 |
|
|
27 |
-- Penlight compatibility
|
|
28 |
utils.unpack = utils.unpack or unpack or table.unpack
|
| 27 | 29 |
|
| 28 | 30 |
local append = table.insert
|
| 29 | 31 |
|
|
| 148 | 150 |
ldoc.alias(name,{'param',modifiers={type=type}})
|
| 149 | 151 |
end
|
| 150 | 152 |
|
| 151 | |
ldoc.alias ('error',function(tags,value)
|
| 152 | |
local g = '2'
|
| 153 | |
tags:add('return','',{[g]=true,type='nil'})
|
| 154 | |
return 'return', value, {[g]=true,type='string'}
|
| 155 | |
end)
|
|
153 |
ldoc.alias ('error',doc.error_macro)
|
| 156 | 154 |
|
| 157 | 155 |
ldoc.tparam_alias 'string'
|
| 158 | 156 |
ldoc.tparam_alias 'number'
|
| 15 | 15 |
function mul2 () end
|
| 16 | 16 |
|
| 17 | 17 |
-----
|
|
18 |
-- function with multiple error tags
|
|
19 |
-- @return result
|
|
20 |
-- @error[1] not found
|
|
21 |
-- @error[2] bad format
|
|
22 |
function mul3 () end
|
|
23 |
|
|
24 |
-----
|
| 18 | 25 |
-- function that raises an error.
|
| 19 | 26 |
-- @string filename
|
| 20 | 27 |
-- @treturn string result
|
| 21 | 28 |
-- @raise 'file not found'
|
| 22 | |
function mul3(filename) end
|
|
29 |
function mul4(filename) end
|