[policy_chain] improve policy chain documentation

gateway/src/apicast/policy_chain.lua

@@ -67,8 +67,8 @@ end
 -- If the module is a string, returns the result of initializing it with the
 -- given arguments. Otherwise, this function simply returns the module
 -- received.
--- @tparam string/object The module
--- @tparam[opt] params needed to initialize the module
+-- @tparam string|table module the module or its name
+-- @tparam ?table ... params needed to initialize the module
 -- @treturn object The module instantiated
 function _M.load(module, ...)
     if type(module) == 'string' then
@@ -85,6 +85,8 @@ function _M.load(module, ...)
     end
 end
 
+--- Initialize new @{PolicyChain}.
+-- @treturn PolicyChain
 function _M.new(list)
     local chain = list or {}
 
@@ -93,6 +95,10 @@ function _M.new(list)
     return self
 end
 
+---------------------
+--- @type PolicyChain
+-- An instance of @{policy_chain}.
+
 --- Export the shared context of the chain
 -- @treturn linked_list The context of the chain. Note: the list returned is
 --   read-only.
@@ -111,7 +117,7 @@ end
 
 --- Freeze the policy chain to prevent modifications.
 -- After calling this method it won't be possible to insert more policies.
--- @treturn self
+-- @treturn PolicyChain returns self
 function _M:freeze()
     self.frozen = true
     return self
@@ -120,11 +126,15 @@ end
 --- Insert a policy into the chain
 -- @tparam Policy policy the policy to be added to the chain
 -- @tparam[opt] int position the position to add the policy to, defaults to last one
+-- @treturn int lenght of the chain
+-- @error frozen | returned when chain is not modifiable
+-- @see freeze
 function _M:insert(policy, position)
     if self.frozen then
-        return nil, 'frozen chain'
+        return nil, 'frozen'
     else
         insert(self, position or #self+1, policy)
+        return #self
     end
 end
 

spec/policy_chain_spec.lua

@@ -119,7 +119,7 @@ describe('policy_chain', function()
       local ok, err = chain:insert(policy, 1)
 
       assert.is_nil(ok)
-      assert.equal(err, 'frozen chain')
+      assert.equal(err, 'frozen')
       assert.equal(0, #chain)
     end)
   end)