tabulous: add documentation, cleanup

Signed-off-by: Julien Danjou <julien@danjou.info>

lib/tabulous.lua

@@ -22,13 +22,13 @@ local client = client
 local table = table
 local pairs = pairs
 local awful = awful
-local print = print
 
 -- Reset env
 setfenv(1, P)
 
-local tabbed = {}
+tabbed = {}
 
+-- Hook creation
 awful.hooks.userhook_create('tabbed')
 awful.hooks.userhook_create('untabbed')
 awful.hooks.userhook_create('tabdisplay')
@@ -38,18 +38,22 @@ awful.hooks.userhook_create('tabhide')
 -- Functions --
 ---------------
 
--- Find the key in a table
+--- Find a key in a table.
-local function findkey(table, cl)
+-- @param table The table to look into
-    for i, c in pairs(table) do
+-- @param value The value to find.
-        if c == cl then
+-- @return The key or nil if not found.
-            return i
+function P.findkey(table, value)
+    for k, v in pairs(table) do
+        if v == value then
+            return k
         end
     end
-    return nil
 end
 
--- Swap which tab is displayed
+--- Swap and select which client in tab is displayed.
-local function client_display(tabindex, cl)
+-- @param tabindex The tab index.
+-- @param cl The client to show.
+function P.display(tabindex, cl)
     local p = tabbed[tabindex][1]
     
     if cl and p ~= cl then
@@ -65,19 +69,24 @@ local function client_display(tabindex, cl)
     end
 end
 
--- Check if the client is in the given tabindex
+--- Check if the client is in the given tabindex.
-local function client_in_tabindex(tabindex, cl)
+-- @param tabindex The tab index.
+-- @param cl The client
+-- @return The key.
+function P.tabindex_check(tabindex, cl)
     local c = cl or client.focus_get()
-    return findkey(tabbed[tabindex], c)
+    return P.findkey(tabbed[tabindex], c)
 end
 
--- Find the tab index or return nil if not tabbed
+--- Find the tab index or return nil if not tabbed.
-local function client_find_tabindex(cl)
+-- @param cl The client to search.
+-- @return The tab index.
+function P.tabindex_get(cl)
     local c = cl or client.focus_get()
 
     for tabindex, tabdisplay in pairs(tabbed) do
         -- Loop through all tab displays
-        local me = client_in_tabindex(tabindex, c)
+        local me = P.tabindex_check(tabindex, c)
 
         if me ~= nil then
             return tabindex 
@@ -87,29 +96,39 @@ local function client_find_tabindex(cl)
     return nil
 end
 
--- Get all clients on a tabbed display
+--- Get all clients on a tabbed display.
-local function client_get_clients(tabindex)
+-- @param tabindex The tab index.
+-- @return All tabbed clients.
+function P.clients_get(tabindex)
     if tabbed[tabindex] == nil then return nil end
     return tabbed[tabindex][2]
 end
 
--- Get the displayed client on a tabbed display
+--- Get the displayed client on a tabbed display.
-local function client_get_displayed(tabindex)
+-- @param tabindex The tab index.
+-- @return The displayed client.
+function P.displayed_get(tabindex)
     if tabbed[tabindex] == nil then return nil end
     return tabbed[tabindex][1]
 end
 
--- Get a client by tab number
+--- Get a client by tab number.
-local function client_get_position(tabindex, pos)
+-- @param tabindex The tab index.
+-- @param pos The position in the tab.
+-- @return The client at the given position.
+function P.position_get(tabindex, pos)
     if tabbed[tabindex] == nil then return nil end
     return tabbed[tabindex][2][pos]
 end
 
--- Get the next client in a tabdisplay
+--- Get the next client in a tab display.
-local function client_next(tabindex, cl)
+-- @param tabindex The tab index.
+-- @param cl The current client.
+-- @return The next client.
+function P.next(tabindex, cl)
     local c = cl or tabbed[tabindex][1]
 
-    local i = findkey(tabbed[tabindex][2], c)
+    local i = P.findkey(tabbed[tabindex][2], c)
 
     if i == nil then
         return nil
@@ -117,16 +136,19 @@ local function client_next(tabindex, cl)
 
     if tabbed[tabindex][2][i+1] == nil then
         return tabbed[tabindex][2][1]
-    else
-        return tabbed[tabindex][2][i+1]
     end
+
+    return tabbed[tabindex][2][i + 1]
 end
 
--- Get the previous client in a tabdisplay
+--- Get the previous client in a tabdisplay
-local function client_prev(tabindex, cl)
+-- @param tabindex The tab index.
+-- @param cl The current client.
+-- @return The previous client.
+function P.prev(tabindex, cl)
     local c = cl or tabbed[tabindex][1]
 
-    local i = findkey(tabbed[tabindex][2], c)
+    local i = P.findkey(tabbed[tabindex][2], c)
 
     if i == nil then
         return nil
@@ -134,21 +156,24 @@ local function client_prev(tabindex, cl)
 
     if tabbed[tabindex][2][i-1] == nil then
         return tabbed[tabindex][2][table.maxn(tabbed[tabindex][2])]
-    else
-        return tabbed[tabindex][2][i-1]
     end
+
+    return tabbed[tabindex][2][i - 1]
 end
 
--- Remove a client from a tabbed display
+--- Remove a client from a tabbed display.
-local function client_untab(cl)
+-- @param cl The client to remove.
+-- @return True if the client has been untabbed.
+function P.untab(cl)
     local c = cl or client.focus_get()
-    local tabindex = client_find_tabindex(c)
+    local tabindex = P.tabindex_get(c)
+
     if tabindex == nil then return false end
 
-    local cindex = findkey(tabbed[tabindex][2], c)
+    local cindex = P.findkey(tabbed[tabindex][2], c)
 
     if tabbed[tabindex][1] == c then
-        client_display(tabindex, client_next(tabindex, c))
+        P.display(tabindex, P.next(tabindex, c))
     end
 
     table.remove(tabbed[tabindex][2], cindex)
@@ -162,8 +187,9 @@ local function client_untab(cl)
     awful.hooks.userhook_call('untabbed', {c})
 end
 
--- Untab all clients in a tabbed display
+--- Untab all clients in a tabbed display.
-local function client_untab_all(tabindex)
+-- @param tabindex The tab index.
+function P.untab_all(tabindex)
     for i,c in pairs(tabbed[tabindex][2]) do
         c:hide(false)
         awful.hooks.userhook_call('untabbed', {c})
@@ -174,85 +200,69 @@ local function client_untab_all(tabindex)
     end
 end
 
--- Create a new tabbed display with client as the master
+--- Create a new tabbed display with client as the master.
-local function client_tab_create(cl)
+-- @param cl The client to set into the tab, focused one otherwise.
+-- @return The created tab index.
+function P.tab_create(cl)
     local c = cl or client.focus_get()
 
+    if not c then return end
+
     table.insert(tabbed, {
-        c, -- Window currently being displayed
+        c,    -- Window currently being displayed
         { c } -- List of windows in tabbed display
     })
 
     awful.hooks.userhook_call('tabbed', {c})
-    return client_find_tabindex(c)
+    return P.tabindex_get(c)
 end
 
--- Add a client to a tabbed display
+--- Add a client to a tabbed display.
-local function client_tab(tabindex, cl)
+-- @param tabindex The tab index.
+-- @param cl The client to add, or the focused one otherwise.
+function P.tab(tabindex, cl)
     local c = cl or client.focus_get()
 
     if tabbed[tabindex] ~= nil then
-        local x = client_find_tabindex(c)
+        local x = P.tabindex_get(c)
 
         if x == nil then
             -- Add untabbed client to tabindex
             table.insert(tabbed[tabindex][2], c)
-            client_display(tabindex, c)
+            P.display(tabindex, c)
 
             awful.hooks.userhook_call('tabbed', {c})
         elseif x ~= tabindex then
             -- Merge two tabbed views
             local cc = tabbed[tabindex][1]
-            local clients = client_get_clients(x)
+            local clients = P.clients_get(x)
-            client_untab_all(x)
+            P.untab_all(x)
 
-            tabindex = client_find_tabindex(cc)
+            tabindex = P.tabindex_get(cc)
 
             for i,b in pairs(clients) do
-                client_tab(tabindex, b)
+                P.tab(tabindex, b)
             end
         end
     end
 end
 
--- Start autotabbing, this automatically
+--- Start autotabbing, this automatically tabs new clients when the current
--- tabs new clients when the current client
+-- client is tabbed.
--- is tabbed
+function P.autotab_start()
-local function autotab_start()
     awful.hooks.manage(function (c)
         local sel = client.focus_get()
-        local index = client_find_tabindex(sel)
+        local index = P.tabindex_get(sel)
 
         if index ~= nil then
             -- Currently focussed client is tabbed, 
             -- add the new window to the tabbed display
-            client_tab(index, c)
+            P.tab(index, c)
         end
     end)
 end
 
 -- Set up hook so we don't leave lost hidden clients
-awful.hooks.unmanage(function (c) client_untab(c) end)
+awful.hooks.unmanage(function (c) P.untab(c) end)
-
-P.findkey = findkey
-P.display = client_display
-P.tabindex_check = client_in_tabindex
-P.tabindex_get = client_find_tabindex
-
-P.tab_create = client_tab_create
-P.tab = client_tab
-P.untab = client_untab
-P.untab_all = client_untab_all
-
-P.next = client_next
-P.prev = client_prev
-
-P.clients_get = client_get_clients
-P.displayed_get = client_get_displayed
-P.position_get = client_get_position
-
-P.autotab_start = autotab_start
-
-P.tabbed = tabbed
 
 return P