From 25fca23772b8de4289f00c9e83049473a5bd1c16 Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Thu, 3 Jan 2019 17:06:05 +0100 Subject: [PATCH] doc: revisit gears.table --- lib/gears/table.lua | 84 ++++++++++++++++++++++----------------------- 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/lib/gears/table.lua b/lib/gears/table.lua index 3cf3645ba..be0a9a9e6 100644 --- a/lib/gears/table.lua +++ b/lib/gears/table.lua @@ -10,12 +10,12 @@ local rtable = table local gmath = require("gears.math") local gtable = {} ---- Join all tables given as parameters. --- This will iterate all tables and insert all their keys into a new table. +--- Join all tables given as arguments. +-- 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 --- @return A new table containing all keys from the arguments. +-- @tparam table ... Tables to join. +-- @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 --- @treturn table A packed table with all numeric keys +-- @tparam table t A potentially sparse table. +-- @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 --- @return A table with keys +-- @tparam table t The table for which the keys to get. +-- @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 --- @param ... the types to look for --- @return A filtered table with keys +-- @tparam table t The table to retrieve the keys for. +-- @tparam string ... The types to look for. +-- @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 --- @return the reversed table +-- @tparam table t The table to reverse. +-- @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 --- @param deep Create a deep clone? (default: true) --- @return a clone of t +-- @tparam table t The table to clone. +-- @tparam[opt=true] bool deep Create a deep clone? +-- @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 ---- --- Returns an iterator to cycle through, starting from the first element or the --- given index, all elements of a table that match a given criteria. +--- Iterate over a table. +-- Returns an iterator to cycle through all elements of a table that match a +-- 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 the one table to another one +--- Merge items from one table to another one. -- @class function -- @name merge --- @tparam table t the container table --- @tparam table set the mixin table --- @treturn table Return `t` for convenience +-- @tparam table t The container table +-- @tparam table set The mixin table. +-- @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 --- on the table, returning a table of the results. +--- Map a function to a table. +-- 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 table tbl the container table whose values will be operated on --- @treturn table Return a table of the results +-- @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. +-- @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