[algo] Improve documentation.

algo.lua

@@ -12,16 +12,19 @@ local algo = {}
 
 --- Clamp x within range [a,b] (where b >= a).
 --
--- @param x (number) value to clamp.
--- @param a (number) interval lower bound (inclusive).
--- @param b (number) interval upper bound (includive).
--- @return (number) clamped value.
+-- @number x value to clamp.
+-- @number a interval lower bound (inclusive).
+-- @number b interval upper bound (includive).
+-- @treturn number clamped value.
 function algo.clamp(x, a, b) return min(max(x, a), b) end
 
 --- Fast remove from array.
 --
 -- Replace 'array[i]' with last array's element and
 -- discard array's tail.
+--
+-- @tparam table array
+-- @int i
 function algo.removefast(array, i)
     local n = #array
 
@@ -37,10 +40,11 @@ local function lt(a, b) return a < b end
 -- Performs better than regular table.sort() for small arrays
 -- (~100 elements).
 --
--- @param array (table) array to be sorted.
--- @param less (function|nil) comparison function, takes 2 arguments,
---             returns true if its first argument is less than its second argument, false otherwise.
---             Defaults to operator <.
+-- @tparam table array array to be sorted.
+-- @tparam[opt=operator <] function less comparison function, takes 2 arguments,
+--                                  returns true if its first argument is
+--                                  less than its second argument,
+--                                  false otherwise.
 function algo.insertionsort(array, less)
     less = less or lt
 
@@ -60,15 +64,16 @@ end
 --- Binary search last element where
 --  what <= array[i] - also known as lower bound.
 --
--- @param array (table) an array sorted according to the less function.
+-- @tparam table array an array sorted according to the less function.
 -- @param what the comparison argument.
--- @param less (function|nil) sorting criterium, a function taking 2 arguments,
---             returns true if the first argument is less than the second argument,
---             false otherwise. Defaults to using the < operator.
+-- @tparam[opt=operator <] function less sorting criterium, a function taking 2 arguments,
+--                                  returns true if the first argument
+--                                  is less than the second argument,
+--                                  false otherwise.
 --
--- @return (number) the greatest index i, where what <= array[i].
---         If no such element exists, it returns an out of bounds index
---         such that array[i] == nil.
+-- @treturn int the greatest index i, where what <= array[i].
+--              If no such element exists, it returns an out of bounds index
+--              such that array[i] == nil.
 function algo.bsearchl(array, what, less)
     less = less or lt
 
@@ -94,15 +99,17 @@ end
 --- Binary search first element where
 --  what >= array[i] - also known as upper bound.
 --
--- @param array (array) an array sorted according to the less function.
+-- @tparam table array an array sorted according to the less function.
 -- @param what the comparison argument.
--- @param less (function|nil) sorting criterium, a function taking 2 arguments,
---             returns true if the first argument is less than the second argument,
---             false otherwise. Defaults to using the < operator.
+-- @tparam[opt=operator <] function less sorting criterium,
+--                                  a function taking 2 arguments,
+--                                  returns true if the first argument
+--                                  is less than the second argument,
+--                                  false otherwise.
 --
--- @return (number) the smallest index i, where what >= array[i].
---         If no such element exists, it returns an out of bounds index
---         such that array[i] == nil.
+-- @treturn int the smallest index i, where what >= array[i].
+--              If no such element exists, it returns an out of bounds index
+--              such that array[i] == nil.
 function algo.bsearchr(array, what, less)
     less = less or lt