PL utils.unpack compatibility; refactoring error 'tag'

doc/doc.md

@@ -375,7 +375,8 @@ function as well.)
 `@set` is a powerful tag which assigns a configuration variable to a value _just for this module_.
 Saying `@set no_summary=true` in a module comment will temporarily disable summary generation when
 the template is expanded. Generally configuration variables that effect template expansion
-are modifiable in this way.
+are modifiable in this way.  For instance, if you wish that the contents of a particular module
+be sorted, then `@set sort=true` will do it _just_ for that module.
 
 ## Sections
 
@@ -830,8 +831,11 @@ description. There are then sections for the following tags: 'param', 'usage', '
 'see' in that order. (For tables, 'Fields' is used instead of 'Parameters' but internally
 fields of a table are stored as the 'param' tag.)
 
+By default, the items appear in the order of declaration within their section. If `sort=true`
+then they will be sorted alphabetically. (This can be set per-module with @{Module_Tags|@set}.)
+
 You can of course customize the default template, but there are some parameters that can
-control what the template will generate. Setting `one` to `true` in your configuration file
+control what the template will generate. Setting `one=true` in your configuration file
 will give a _one-column_ layout, which can be easier to use as a programming reference.  You
 can suppress the contents summary with `no_summary`.
 

ldoc.lua

@@ -25,6 +25,8 @@ local List = require 'pl.List'
 local stringx = require 'pl.stringx'
 local tablex = require 'pl.tablex'
 
+-- Penlight compatibility
+utils.unpack = utils.unpack or unpack or table.unpack
 
 local append = table.insert
 
@@ -149,11 +151,7 @@ function ldoc.tparam_alias (name,type)
    ldoc.alias(name,{'param',modifiers={type=type}})
 end
 
-ldoc.alias ('error',function(tags,value)
+ldoc.alias ('error',doc.error_macro)
-    local g = '2'
-    tags:add('return','',{[g]=true,type='nil'})
-    return 'return', value, {[g]=true,type='string'}
-end)
 
 ldoc.tparam_alias 'string'
 ldoc.tparam_alias 'number'

ldoc/doc.lua

@@ -772,6 +772,26 @@ function Item:default_of_param(p)
    return opt
 end
 
+function Item:subparam(p)
+   local subp = rawget(self.subparams,p)
+   if subp then
+      return subp,p
+   else
+      return {p},nil
+   end
+end
+
+function Item:display_name_of(p)
+   local pname,field = split_iden(p)
+   if field then
+      return field
+   else
+      return pname
+   end
+end
+
+-------- return values and types -------
+
 function Item:type_of_ret(idx)
    local rparam = self.modifiers['return'][idx]
    return rparam and rparam.type or ''
@@ -829,23 +849,15 @@ function Item:build_return_groups()
    end
 end
 
-function Item:subparam(p)
+-- this alias macro implements @error.
-   local subp = rawget(self.subparams,p)
+-- Alias macros need to return the same results as Item:check_tags...
-   if subp then
+function doc.error_macro(tags,value,modifiers)
-      return subp,p
+   local key = integer_keys(modifiers)
-   else
+   local g = key > 0 and tostring(key) or '2'
-      return {p},nil
+   tags:add('return','',{[g]=true,type='nil'})
-   end
+   return 'return', value, {[g]=true,type='string'}
 end
 
-function Item:display_name_of(p)
-   local pname,field = split_iden(p)
-   if field then
-      return field
-   else
-      return pname
-   end
-end
 
 function Item:warning(msg)
    local file = self.file and self.file.filename

tests/styles/multiple.lua

@@ -15,9 +15,16 @@ function mul1 () end
 -- @error message
 function mul2 () end
 
+-----
+-- function with multiple error tags
+-- @return  result
+-- @error[1] not found
+-- @error[2] bad format
+function mul3 () end
+
 -----
 -- function that raises an error.
 -- @string filename
 -- @treturn string result
 -- @raise 'file not found'
-function mul3(filename) end
+function mul4(filename) end