doc: revisit gears.table

lib/gears/table.lua

@@ -10,12 +10,12 @@ local rtable = table
 local gmath = require("gears.math")
 local gtable = {}
 
---- Join all tables given as parameters.
+--- Join all tables given as arguments.
--- This will iterate all tables and insert all their keys into a new table.
+-- This will iterate over all tables and insert their entries into a new table.
 -- @class function
 -- @name join
--- @param args A list of tables to join
+-- @tparam table ... Tables to join.
--- @return A new table containing all keys from the arguments.
+-- @treturn table A new table containing all entries from the arguments.
 function gtable.join(...)
     local ret = {}
     for i = 1, select("#", ...) do
@@ -40,7 +40,7 @@ end
 -- @name crush
 -- @tparam table t the table to be overriden
 -- @tparam table set the table used to override members of `t`
--- @tparam[opt=false] boolean raw Use rawset (avoid the metatable)
+-- @tparam[opt=false] bool raw Use rawset (avoid the metatable)
 -- @treturn table t (for convenience)
 function gtable.crush(t, set, raw)
     if raw then
@@ -56,17 +56,17 @@ function gtable.crush(t, set, raw)
     return t
 end
 
---- Pack all elements with an integer key into a new table
+--- Pack all elements with an integer key into a new table.
 -- While both lua and luajit implement __len over sparse
--- table, the standard define it as an implementation
+-- tables, the standard defines it as an implementation
 -- detail.
 --
--- This function remove any non numeric keys from the value set
+-- This function removes any entries with non-numeric keys.
 --
 -- @class function
 -- @name from_sparse
--- @tparam table t A potentially sparse table
+-- @tparam table t A potentially sparse table.
--- @treturn table A packed table with all numeric keys
+-- @treturn table A packed table with only numeric keys.
 function gtable.from_sparse(t)
     local keys= {}
     for k in pairs(t) do
@@ -88,9 +88,10 @@ end
 --- Check if a table has an item and return its key.
 -- @class function
 -- @name hasitem
--- @param t The table.
+-- @tparam table t The table.
 -- @param item The item to look for in values of the table.
--- @return The key were the item is found, or nil if not found.
+-- @treturn[1] string|number The key of the item.
+-- @treturn[2] nil
 function gtable.hasitem(t, item)
     for k, v in pairs(t) do
         if v == item then
@@ -99,11 +100,11 @@ function gtable.hasitem(t, item)
     end
 end
 
---- Get a sorted table with all integer keys from a table
+--- Get a sorted table with all integer keys from a table.
 -- @class function
 -- @name keys
--- @param t the table for which the keys to get
+-- @tparam table t The table for which the keys to get.
--- @return A table with keys
+-- @treturn table A table with keys
 function gtable.keys(t)
     local keys = { }
     for k, _ in pairs(t) do
@@ -115,12 +116,12 @@ function gtable.keys(t)
     return keys
 end
 
---- Filter a tables keys for certain content types
+--- Filter a table's keys for certain content type.
 -- @class function
 -- @name keys_filter
--- @param t The table to retrieve the keys for
+-- @tparam table t The table to retrieve the keys for.
--- @param ... the types to look for
+-- @tparam string ... The types to look for.
--- @return A filtered table with keys
+-- @treturn table A filtered table.
 function gtable.keys_filter(t, ...)
     local keys = gtable.keys(t)
     local keys_filtered = { }
@@ -135,18 +136,18 @@ function gtable.keys_filter(t, ...)
     return keys_filtered
 end
 
---- Reverse a table
+--- Reverse a table.
 -- @class function
 -- @name reverse
--- @param t the table to reverse
+-- @tparam table t The table to reverse.
--- @return the reversed table
+-- @treturn table A reversed table.
 function gtable.reverse(t)
     local tr = { }
-    -- reverse all elements with integer keys
+    -- Reverse all elements with integer keys.
     for _, v in ipairs(t) do
         rtable.insert(tr, 1, v)
     end
-    -- add the remaining elements
+    -- Add the remaining elements.
     for k, v in pairs(t) do
         if type(k) ~= "number" then
             tr[k] = v
@@ -155,12 +156,12 @@ function gtable.reverse(t)
     return tr
 end
 
---- Clone a table
+--- Clone a table.
 -- @class function
 -- @name clone
--- @param t the table to clone
+-- @tparam table t The table to clone.
--- @param deep Create a deep clone? (default: true)
+-- @tparam[opt=true] bool deep Create a deep clone?
--- @return a clone of t
+-- @treturn table A clone of `t`.
 function gtable.clone(t, deep)
     deep = deep == nil and true or deep
     local c = { }
@@ -174,9 +175,9 @@ function gtable.clone(t, deep)
     return c
 end
 
----
+--- Iterate over a table.
--- Returns an iterator to cycle through, starting from the first element or the
+-- Returns an iterator to cycle through all elements of a table that match a
--- given index, all elements of a table that match a given criteria.
+-- given criteria, starting from the first element or the given index.
 --
 -- @class function
 -- @name iterate
@@ -202,13 +203,12 @@ function gtable.iterate(t, filter, start)
     end
 end
 
-
+--- Merge items from one table to another one.
---- Merge items from the one table to another one
 -- @class function
 -- @name merge
--- @tparam table t the container table
+-- @tparam table t The container table
--- @tparam table set the mixin table
+-- @tparam table set The mixin table.
--- @treturn table Return `t` for convenience
+-- @treturn table (for convenience)
 function gtable.merge(t, set)
     for _, v in ipairs(set) do
         table.insert(t, v)
@@ -216,13 +216,14 @@ function gtable.merge(t, set)
     return t
 end
 
---- Map a function to a table. The function is applied to each value
+--- Map a function to a table.
--- on the table, returning a table of the results.
+-- The function is applied to each value on the table, returning a modified
+-- table.
 -- @class function
 -- @name map
--- @tparam function f the function to be applied to each value on the table
+-- @tparam function f The function to be applied to each value in the table.
--- @tparam table tbl the container table whose values will be operated on
+-- @tparam table tbl The container table whose values will be operated on.
--- @treturn table Return a table of the results
+-- @treturn table
 function gtable.map(f, tbl)
     local t = {}
     for k,v in pairs(tbl) do
@@ -231,5 +232,4 @@ function gtable.map(f, tbl)
     return t
 end
 
-
 return gtable