Merge pull request #3288 from Aire-One/feature/ldoc-inheritance-diagram

[doc] Add ldoc @supermodule tag to draw inheritance diagram and manage inherited properties

docs/config.ld

@@ -456,6 +456,25 @@ add_custom_tag {
     },
 }
 
+-- Define the supermodule class.
+-- This tag should be used at the module level. All properties from the
+-- supermodule will be recursively added to the module by our ldoc template.
+-- @supermodule supermodule
+add_custom_tag {
+    name = "supermodule",
+    hidden = true,
+    auto_subtags = false
+}
+
+-- Mark the item ad hidden.
+-- This tag should be used to hide items from the documentation.
+-- @hidden
+add_custom_tag {
+    name = "hidden",
+    hidden = true,
+    auto_subtags = false
+}
+
 -- More fitting section names
 kind_names={topic='Documentation', module='Libraries', script='Sample files'}
 

docs/ldoc.css

@@ -503,3 +503,32 @@ pre .url { color: #272fc2; text-decoration: underline; }
 .index_guides div a:hover {
     background-color: #99b3ec;
 }
+
+/* Inheritance diagram */
+.inheritance .inheritance__level {
+    list-style: none;
+}
+
+.inheritance .inheritance__level--root {
+    padding-left: 0;
+}
+
+.inheritance .inheritance__level__node::before {
+    content: "↳";
+}
+
+.inheritance .inheritance__level__node--root::before {
+    /* simulate the spacing of the arrow character */
+    content: "   ";
+    white-space: pre;
+}
+
+.extra-header {
+    display: flex;
+    flex-direction: row;
+    flex-wrap: wrap;
+}
+
+.extra-header__section {
+    flex-grow: 1;
+}

docs/ldoc.ltp

@@ -43,6 +43,80 @@
 # local html_space = function(s) return s:gsub(" ", "%%20") end
 # local no_underscores = function(s) return s:gsub("_", " ") end
 
+# --------- modules hierarchy -------------
+# local hierarchy = {}
+# local curr = module
+# while curr do
+#     hierarchy[#hierarchy + 1] = curr
+#     -- no need to do anything more if there is no explicite @supermodule
+#     if not curr.tags.supermodule then break end
+#     local super = curr.tags.supermodule[1] -- only consider one way inheritance
+#     local found = false
+#     for kind, mods, type in ldoc.kinds() do
+#         for mod in mods() do
+#             local name = display_name(mod)
+#             if name == super then
+#                 curr = mod
+#                 found = true
+#             end
+#             if found then break end
+#         end
+#         if found then break end
+#     end
+#     if not found then curr = nil end
+# end
+
+# --------- merge modules content with supermodules -------------
+# local all_module_kinds = {}
+# if module then
+# for kind,items in module.kinds() do
+#     local myitems = {}
+#     for item in items() do
+#       myitems[#myitems + 1] = item
+#      end
+#     all_module_kinds[#all_module_kinds + 1] = { kind = kind,  items = myitems }
+# end
+# local filtered_kinds = { "Constructors", "Static module functions",
+#   "Functions", "Methods", "lib.gears.object.properties Functions" }
+# for supermodule in iter(hierarchy) do
+#     for kind,items in supermodule.kinds() do
+#         local ignored = false
+#         for _,filtered in ldoc.pairs(filtered_kinds) do
+#             if kind == filtered then
+#                 ignored = true
+#                 break
+#             end
+#         end
+#         if not ignored then
+#             local curr_kind = nil
+#             for k in iter(all_module_kinds) do
+#                 if k.kind == kind then
+#                     curr_kind = k
+#                     break
+#                 end
+#             end
+#             if not curr_kind then
+#                 curr_kind  = { kind = kind, items = {} }
+#                 all_module_kinds[#all_module_kinds + 1] = curr_kind
+#             end
+#             for item in items() do
+#                 local tobeadded = true
+#                 for i in iter(curr_kind.items) do
+#                     if item.name == i.name then
+#                         tobeadded = false
+#                         break
+#                     end
+#                 end
+#                 if tobeadded then
+#                     item.inherited = true -- force inherited status
+#                     curr_kind.items[#curr_kind.items + 1] = item
+#                 end
+#             end
+#         end
+#     end
+# end
+# end
+
 <!-- Menu -->
 
 <div id="navigation">
@@ -59,7 +133,8 @@
 # if module and not ldoc.no_summary and #module.items > 0 then
 <h2>Contents</h2>
 <ul>
-# for kind,items in module.kinds() do
+# for k in iter(all_module_kinds) do
+#  local kind = k.kind
 #  if not kind:match("^ldoc_skip") then
 <li><a href="#$(no_spaces(kind))">$(kind)</a></li>
 # end
@@ -109,18 +184,6 @@
 <h1>Module: <code>$(module.name)</code></h1>
 <p>$(M(module.summary,module))</p>
 <p>$(M(module.description,module))</p>
-#   if module.tags.include then
-        $(M(ldoc.include_file(module.tags.include)))
-#   end
-#   if module.see then
-#     local li,il = use_li(module.see)
-    <h3>See also:</h3>
-    <ul>
-#     for see in iter(module.see) do
-         $(li)<a href="$(ldoc.href(see))">$(see.label)</a>$(il)
-#    end -- for
-    </ul>
-#   end -- if see
 #   if module.usage then
 #     local li,il = use_li(module.usage)
     <h3>Usage:</h3>
@@ -130,20 +193,75 @@
 #     end -- for
     </ul>
 #   end -- if usage
+<div class="extra-header">
+# if module.tags.supermodule or module.tags.knownusage then
+  <div class="extra-header__section">
+    <h3>Class Hierarchy</h3>
+    <div class="inheritance">
+# local function draw_hierary_recursifly(i)
+#   local is_root_level = (i == #hierarchy)
+    <ul class="inheritance__level $(is_root_level and 'inheritance__level--root' or '')">
+        <li class="inheritance__level__node $(is_root_level and 'inheritance__level__node--root' or '')">
+#   local mod = hierarchy[i]
+#   local name = display_name(hierarchy[i])
+#   if mod == module then
+            <strong>$(name)</strong>
+#   else
+            <a href="$(ldoc.ref_to_module(mod))">$(name)</a>
+#   end
+        </li>
+#   if i > 1 then
+        <li>
+#           draw_hierary_recursifly(i - 1)
+        </li>
+#   end
+    </ul>
+# end -- module.tags.supermodule
+# draw_hierary_recursifly(#hierarchy)
+    </div>
+# end
+
+#   if module.tags.include then
+        $(M(ldoc.include_file(module.tags.include)))
+#   end
+  </div>
 #   if module.info then
+  <div class="extra-header__section">
     <h3>Info:</h3>
     <ul>
 #     for tag, value in module.info:iter() do
             <li><strong>$(tag)</strong>: $(M(value,module))</li>
 #     end
     </ul>
+  </div>
 #   end -- if module.info
+#   if module.see then
+  <div class="extra-header__section">
+#     local li,il = use_li(module.see)
+    <h3>See also:</h3>
+#     if #module.see > 1 then
+    <ul>
+#     else
+    <p>
+#     end
+#     for see in iter(module.see) do
+         $(li)<a href="$(ldoc.href(see))">$(see.label)</a>$(il)
+#    end -- for
+#     if #module.see > 1 then
+    </ul>
+#     else
+    </p>
+#     end
+  </div>
+#   end -- if see
+</div>
 
 
 # if not ldoc.no_summary then
 # -- bang out the tables of item types for this module (e.g Functions, Tables, etc)
 # local last_kind = ""
-# for kind,items in module.kinds() do
+# for k in iter(all_module_kinds) do
+#  local kind = k.kind
 #  if not kind:match("^ldoc_skip") then
 #   if last_kind ~= "" then
 </table>
@@ -151,8 +269,9 @@
 <h2><a href="#$(no_spaces(kind))">$(kind)</a></h2>
 <table class="function_list">
 #  end
-#  for item in items() do
+#  for item in iter(k.items) do if not item.tags.hidden then
 #   local dn = display_name(item)
+#   local inherited = (item.baseclass ~= module.name)
 #   if item.sanitize_type then item.sanitize_type(item, ldoc) end
     <tr>
 #   if item.display_type and not item.compact_signature then
@@ -166,14 +285,14 @@
 #     end
       </td>
 #   end
-      <td colspan="$(item.inherited and 1 or 2)" class="summary">$(M(item.summary,item))</td>
-#   if item.inherited then
-      <td class="baseclass" $(nowrap)>
+      <td colspan="$(inherited and 1 or 2)" class="summary">$(M(item.summary,item))</td>
+#   if inherited then
+      <td class="baseclass" nowrap>
         Inherited from $(item.baseclass)
       </td>
 #   end
     </tr>
-#  end -- for items
+#  end end -- for items
 # last_kind = kind
 #end -- for kinds
 </table>
@@ -187,7 +306,8 @@
 # --- function parameters or table fields.
 # local show_return = not ldoc.no_return_or_parms
 # local show_parms, last_kind = show_return, ""
-# for kind, items in module.kinds() do
+# for k in iter(all_module_kinds) do
+#  local kind = k.kind
 #   local kitem = module.kinds:get_item(kind)
 #   local has_description = kitem and ldoc.descript(kitem) ~= ""
 #   if not kind:match("^ldoc_skip") then
@@ -211,7 +331,7 @@
 #  if not kind:match("^ldoc_skip") then
     <dl class="function">
 #  end
-#  for item in items() do
+#  for item in iter(k.items) do if not item.tags.hidden then
     <dt>
     <a name = "$(item.name)"></a>
     <strong>$(display_name(item))</strong>
@@ -225,8 +345,8 @@
     <span class="proptype">$(item.display_type)</span>
 #   end
     <span class="baseclass" $(nowrap)>
-#   if item.inherited then
-    &middot;&nbsp;Inherited from $(item.baseclass)
+#   if item.baseclass ~= module.name then
+    &middot;&nbsp;Inherited from $(M(item.baseclass, item))
 #   end
 #   if item.extra_summary then
 #       for _, col in ldoc.ipairs(item.extra_summary) do
@@ -371,7 +491,7 @@
     </span>
 
 </dd>
-# end -- for items
+# end end -- for items
 #  last_kind = kind
 # end -- for kinds
 </dl>

lib/awful/popup.lua

@@ -19,6 +19,7 @@
 -- @author Emmanuel Lepage Vallee
 -- @copyright 2016 Emmanuel Lepage Vallee
 -- @popupmod awful.popup
+-- @supermodule wibox
 ---------------------------------------------------------------------------
 local wibox     = require( "wibox"           )
 local gtable    = require( "gears.table"     )

lib/awful/tooltip.lua

@@ -40,6 +40,7 @@
 -- @author Sébastien Gross <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org>
 -- @copyright 2009 Sébastien Gross
 -- @popupmod awful.tooltip
+-- @supermodule wibox
 -------------------------------------------------------------------------
 
 local timer = require("gears.timer")

lib/awful/wibar.lua

@@ -11,6 +11,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2016 Emmanuel Lepage Vallee
 -- @popupmod awful.wibar
+-- @supermodule awful.popup
 ---------------------------------------------------------------------------
 
 -- Grab environment we need

lib/awful/widget/button.lua

@@ -6,6 +6,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
 -- @widgetmod awful.widget.button
+-- @supermodule wibox.widget.imagebox
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -65,10 +66,6 @@ function button.mt:__call(...)
     return button.new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(button, button.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/widget/clienticon.lua

@@ -1,7 +1,10 @@
+---------------------------------------------------------------------------
 --- Container showing the icon of a client.
 -- @author Uli Schlachter
 -- @copyright 2017 Uli Schlachter
 -- @widgetmod awful.widget.clienticon
+-- @supermodule wibox.widget.base
+---------------------------------------------------------------------------
 
 local base = require("wibox.widget.base")
 local surface = require("gears.surface")
@@ -123,10 +126,6 @@ client.connect_signal("property::icon", function(c)
     end
 end)
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(clienticon, {
     __call = function(_, ...)
         return new(...)

lib/awful/widget/launcher.lua

@@ -11,6 +11,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
 -- @widgetmod awful.widget.launcher
+-- @supermodule awful.widget.button
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -50,10 +51,6 @@ function launcher.mt:__call(...)
     return launcher.new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(launcher, launcher.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/widget/layoutbox.lua

@@ -6,6 +6,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
 -- @widgetmod awful.widget.layoutbox
+-- @supermodule wibox.layout.fixed
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable

lib/awful/widget/layoutlist.lua

@@ -21,6 +21,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2010, 2018 Emmanuel Lepage Vallee
 -- @widgetmod awful.widget.layoutlist
+-- @supermodule wibox.widget.base
 ----------------------------------------------------------------------------
 
 local capi     = {screen = screen, tag = tag}
@@ -444,8 +445,4 @@ local function new(_, args)
     return ret
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(module, {__call = new})

lib/awful/widget/only_on_screen.lua

@@ -5,6 +5,7 @@
 -- @author Uli Schlachter
 -- @copyright 2017 Uli Schlachter
 -- @containermod awful.widget.only_on_screen
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local type = type
@@ -129,10 +130,6 @@ capi.screen.connect_signal("property::outputs", function()
     end
 end)
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(only_on_screen, only_on_screen.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/widget/prompt.lua

@@ -7,6 +7,7 @@
 -- @copyright 2009 Julien Danjou
 -- @copyright 2018 Aire-One
 -- @widgetmod awful.widget.prompt
+-- @supermodule wibox.container.background
 ---------------------------------------------------------------------------
 
 --- The prompt foreground color.
@@ -158,10 +159,6 @@ function widgetprompt.mt:__call(...)
     return widgetprompt.new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(widgetprompt, widgetprompt.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/gears/object.lua

@@ -46,9 +46,11 @@ function object.add_signal()
 end
 
 --- Connect to a signal.
+--
 --@DOC_text_gears_object_signal_EXAMPLE@
--- @tparam string name The name of the signal
--- @tparam function func The callback to call when the signal is emitted
+--
+-- @tparam string name The name of the signal.
+-- @tparam function func The callback to call when the signal is emitted.
 -- @method connect_signal
 function object:connect_signal(name, func)
     assert(type(func) == "function", "callback must be a function, got: " .. type(func))
@@ -92,10 +94,16 @@ local function make_the_gc_obey(func)
     return func
 end
 
---- Connect to a signal weakly. This allows the callback function to be garbage
--- collected and automatically disconnects the signal when that happens.
--- @tparam string name The name of the signal
--- @tparam function func The callback to call when the signal is emitted
+--- Connect to a signal weakly.
+--
+-- This allows the callback function to be garbage collected and
+-- automatically disconnects the signal when that happens.
+-- **Warning:**
+-- Only use this function if you really, really, really know what you
+-- are doing.
+--
+-- @tparam string name The name of the signal.
+-- @tparam function func The callback to call when the signal is emitted.
 -- @method weak_connect_signal
 function object:weak_connect_signal(name, func)
     assert(type(func) == "function", "callback must be a function, got: " .. type(func))
@@ -104,9 +112,9 @@ function object:weak_connect_signal(name, func)
     sig.weak[func] = make_the_gc_obey(func)
 end
 
---- Disonnect to a signal.
--- @tparam string name The name of the signal
--- @tparam function func The callback that should be disconnected
+--- Disonnect from a signal.
+-- @tparam string name The name of the signal.
+-- @tparam function func The callback that should be disconnected.
 -- @method disconnect_signal
 function object:disconnect_signal(name, func)
     local sig = find_signal(self, name)
@@ -118,8 +126,8 @@ end
 --
 -- @tparam string name The name of the signal
 -- @param ... Extra arguments for the callback functions. Each connected
---   function receives the object as first argument and then any extra arguments
---   that are given to emit_signal()
+--   function receives the object as first argument and then any extra
+--   arguments that are given to emit_signal()
 -- @method emit_signal
 function object:emit_signal(name, ...)
     local sig = find_signal(self, name)

lib/naughty/layout/box.lua

@@ -8,6 +8,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2017 Emmanuel Lepage Vallee
 -- @popupmod naughty.layout.box
+-- @supermodule awful.popup
 ----------------------------------------------------------------------------
 
 local capi       = {screen=screen}

lib/wibox/container/arcchart.lua

@@ -8,6 +8,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2013 Emmanuel Lepage Vallee
 -- @containermod wibox.container.arcchart
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -357,10 +358,6 @@ function arcchart.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(arcchart, arcchart.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/background.lua

@@ -6,6 +6,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @containermod wibox.container.background
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local base = require("wibox.widget.base")
@@ -484,10 +485,6 @@ function background.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(background, background.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/constraint.lua

@@ -5,6 +5,7 @@
 -- @author Lukáš Hrázký
 -- @copyright 2012 Lukáš Hrázký
 -- @containermod wibox.container.constraint
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -176,10 +177,6 @@ function constraint.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(constraint, constraint.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/margin.lua

@@ -5,6 +5,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @containermod wibox.container.margin
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local pairs = pairs
@@ -238,10 +239,6 @@ function margin.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(margin, margin.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/mirror.lua

@@ -5,6 +5,7 @@
 -- @author dodo
 -- @copyright 2012 dodo
 -- @containermod wibox.container.mirror
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local type = type
@@ -129,10 +130,6 @@ function mirror.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(mirror, mirror.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/place.lua

@@ -5,6 +5,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2016 Emmanuel Lepage Vallee
 -- @containermod wibox.container.place
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -203,10 +204,6 @@ function place.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(place, place.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/radialprogressbar.lua

@@ -8,6 +8,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2013 Emmanuel Lepage Vallee
 -- @containermod wibox.container.radialprogressbar
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -281,10 +282,6 @@ function radialprogressbar.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(radialprogressbar, radialprogressbar.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/rotate.lua

@@ -5,6 +5,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @containermod wibox.container.rotate
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local error = error
@@ -149,10 +150,6 @@ function rotate.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(rotate, rotate.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/scroll.lua

@@ -21,6 +21,7 @@
 -- @author Uli Schlachter (based on ideas from Saleur Geoffrey)
 -- @copyright 2015 Uli Schlachter
 -- @containermod wibox.container.scroll
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local cache = require("gears.cache")
@@ -549,10 +550,6 @@ function scroll.step_functions.waiting_nonlinear_back_and_forth(elapsed, size, v
     return (size - visible_size) * state
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return scroll
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/layout/align.lua

@@ -4,6 +4,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @layoutmod wibox.layout.align
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local table = table
@@ -320,10 +321,6 @@ end
 
 --@DOC_fixed_COMMON@
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return align
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/layout/fixed.lua

@@ -4,6 +4,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @layoutmod wibox.layout.fixed
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility with Lua 5.1)
@@ -381,10 +382,6 @@ end
 
 --@DOC_fixed_COMMON@
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return fixed
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/layout/flex.lua

@@ -4,6 +4,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @layoutmod wibox.layout.flex
+-- @supermodule wibox.layout.fixed
 ---------------------------------------------------------------------------
 
 local base = require("wibox.widget.base")
@@ -15,6 +16,16 @@ local gtable = require("gears.table")
 
 local flex = {}
 
+-- {{{ Override inherited properties we want to hide
+
+--- From `wibox.layout.fixed`.
+-- @property fill_space
+-- @tparam boolean fill_space
+-- @propemits true false
+-- @hidden
+
+-- }}}
+
 --- Add some widgets to the given fixed layout.
 --
 -- @tparam widget ... Widgets that should be added (must at least be one).
@@ -208,10 +219,6 @@ end
 
 --@DOC_fixed_COMMON@
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return flex
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/layout/grid.lua

@@ -14,6 +14,7 @@
 -- @author getzze
 -- @copyright 2017 getzze
 -- @layoutmod wibox.layout.grid
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -961,10 +962,6 @@ end
 
 --@DOC_fixed_COMMON@
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(grid, grid.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/layout/manual.lua

@@ -8,6 +8,7 @@
 -- @author Emmanuel Lepage Vallee
 -- @copyright 2016 Emmanuel Lepage Vallee
 -- @layoutmod wibox.layout.manual
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 local gtable = require("gears.table")
 local base = require("wibox.widget.base")
@@ -245,8 +246,4 @@ end
 
 --@DOC_fixed_COMMON@
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(manual_layout, {__call=function(_,...) return new_manual(...) end})

lib/wibox/layout/ratio.lua

@@ -7,6 +7,8 @@
 -- @author Emmanuel Lepage Vallee
 -- @copyright 2016 Emmanuel Lepage Vallee
 -- @layoutmod wibox.layout.ratio
+-- @supermodule wibox.layout.flex
+-- @see 03-declarative-layout.md
 ---------------------------------------------------------------------------
 
 local base  = require("wibox.widget.base" )
@@ -524,10 +526,6 @@ end
 
 --@DOC_fixed_COMMON@
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return ratio
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/layout/stack.lua

@@ -12,6 +12,7 @@
 -- @author Emmanuel Lepage Vallee
 -- @copyright 2016 Emmanuel Lepage Vallee
 -- @layoutmod wibox.layout.stack
+-- @supermodule wibox.layout.fixed
 ---------------------------------------------------------------------------
 
 local base  = require("wibox.widget.base" )
@@ -210,9 +211,5 @@ end
 
 --@DOC_fixed_COMMON@
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(stack, stack.mt)
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/base.lua

@@ -2,6 +2,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @classmod wibox.widget.base
+-- @supermodule gears.object
 ---------------------------------------------------------------------------
 
 local object = require("gears.object")
@@ -17,6 +18,184 @@ local table = table
 
 local base = {}
 
+-- {{{ Properties available on all widgets
+
+--- Get or set the children elements.
+-- @property children
+-- @tparam table children The children.
+-- @baseclass wibox.widget.base
+
+--- Get all direct and indirect children widgets.
+-- This will scan all containers recursively to find widgets
+-- Warning: This method it prone to stack overflow if there is a loop in the
+-- widgets hierarchy. A hierarchy loop is when a widget, or any of its
+-- children, contain (directly or indirectly) itself.
+-- @property all_children
+-- @tparam table children The children.
+-- @baseclass wibox.widget.base
+
+--- Force a widget height.
+-- @property forced_height
+-- @tparam number|nil height The height (`nil` for automatic)
+-- @baseclass wibox.widget.base
+
+--- Force a widget width.
+-- @property forced_width
+-- @tparam number|nil width The width (`nil` for automatic)
+-- @baseclass wibox.widget.base
+
+--- The widget opacity (transparency).
+-- @property opacity
+-- @tparam[opt=1] number opacity The opacity (between 0 and 1)
+-- @baseclass wibox.widget.base
+
+--- The widget visibility.
+-- @property visible
+-- @param boolean
+-- @baseclass wibox.widget.base
+
+--- The widget buttons.
+--
+-- The table contains a list of `awful.button` objects.
+-- @property buttons
+-- @param table
+-- @see awful.button
+-- @baseclass wibox.widget.base
+
+-- }}}
+
+-- {{{ Signals available on the widgets.
+
+--- When the layout (size) change.
+-- This signal is emitted when the previous results of `:layout()` and `:fit()`
+-- are no longer valid.  Unless this signal is emitted, `:layout()` and `:fit()`
+-- must return the same result when called with the same arguments.
+-- @signal widget::layout_changed
+-- @see widget::redraw_needed
+-- @baseclass wibox.widget.base
+
+--- When the widget content changed.
+-- This signal is emitted when the content of the widget changes. The widget will
+-- be redrawn, it is not re-layouted. Put differently, it is assumed that
+-- `:layout()` and `:fit()` would still return the same results as before.
+-- @signal widget::redraw_needed
+-- @see widget::layout_changed
+-- @baseclass wibox.widget.base
+
+--- When a mouse button is pressed over the widget.
+-- @signal button::press
+-- @tparam table self The current object instance itself.
+-- @tparam number lx The horizontal position relative to the (0,0) position in
+-- the widget.
+-- @tparam number ly The vertical position relative to the (0,0) position in the
+-- widget.
+-- @tparam number button The button number.
+-- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift)
+-- @tparam table find_widgets_result The entry from the result of
+-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
+-- the widget.
+-- @tparam widget find_widgets_result.widget The widget being displayed.
+-- @tparam wibox.hierarchy find_widgets_result.hierarchy The hierarchy
+-- managing the widget's geometry.
+-- @tparam number find_widgets_result.x An approximation of the X position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.y An approximation of the Y position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.width An approximation of the width that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.height An approximation of the height that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.widget_width The exact width of the widget
+-- in its local coordinate system.
+-- @tparam number find_widgets_result.widget_height The exact height of the widget
+-- in its local coordinate system.
+-- @see mouse
+-- @baseclass wibox.widget.base
+
+--- When a mouse button is released over the widget.
+-- @signal button::release
+-- @tparam table self The current object instance itself.
+-- @tparam number lx The horizontal position relative to the (0,0) position in
+-- the widget.
+-- @tparam number ly The vertical position relative to the (0,0) position in the
+-- widget.
+-- @tparam number button The button number.
+-- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift)
+-- @tparam table find_widgets_result The entry from the result of
+-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
+-- the widget.
+-- @tparam widget find_widgets_result.widget The widget being displayed.
+-- @tparam wibox.hierarchy find_widgets_result.hierarchy The hierarchy
+-- managing the widget's geometry.
+-- @tparam number find_widgets_result.x An approximation of the X position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.y An approximation of the Y position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.width An approximation of the width that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.height An approximation of the height that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.widget_width The exact width of the widget
+-- in its local coordinate system.
+-- @tparam number find_widgets_result.widget_height The exact height of the widget
+-- in its local coordinate system.
+-- @see mouse
+-- @baseclass wibox.widget.base
+
+--- When the mouse enter a widget.
+-- @signal mouse::enter
+-- @tparam table self The current object instance itself.
+-- @tparam table find_widgets_result The entry from the result of
+-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
+-- the widget.
+-- @tparam widget find_widgets_result.widget The widget being displayed.
+-- @tparam wibox.hierarchy find_widgets_result.hierarchy The hierarchy
+-- managing the widget's geometry.
+-- @tparam number find_widgets_result.x An approximation of the X position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.y An approximation of the Y position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.width An approximation of the width that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.height An approximation of the height that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.widget_width The exact width of the widget
+-- in its local coordinate system.
+-- @tparam number find_widgets_result.widget_height The exact height of the widget
+-- in its local coordinate system.
+-- @see mouse
+-- @baseclass wibox.widget.base
+
+--- When the mouse leave a widget.
+-- @signal mouse::leave
+-- @tparam table self The current object instance itself.
+-- @tparam table find_widgets_result The entry from the result of
+-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
+-- the widget.
+-- @tparam widget find_widgets_result.widget The widget being displayed.
+-- @tparam wibox.hierarchy find_widgets_result.hierarchy The hierarchy
+-- managing the widget's geometry.
+-- @tparam number find_widgets_result.x An approximation of the X position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.y An approximation of the Y position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.width An approximation of the width that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.height An approximation of the height that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.widget_width The exact width of the widget
+-- in its local coordinate system.
+-- @tparam number find_widgets_result.widget_height The exact height of the widget
+-- in its local coordinate system.
+-- @see mouse
+-- @baseclass wibox.widget.base
+
+-- }}}
+
 -- {{{ Functions on widgets
 
 -- Functions available on all widgets.
@@ -30,7 +209,8 @@ end, true)
 
 --- Set a widget's visibility.
 -- @tparam boolean b Whether the widget is visible.
--- @method set_visible
+-- @method wibox.widget.base:set_visible
+-- @hidden
 function base.widget:set_visible(b)
     if b ~= self._private.visible then
         self._private.visible = b
@@ -42,6 +222,7 @@ end
 
 --- Add a new `awful.button` to this widget.
 -- @tparam awful.button button The button to add.
+-- @method wibox.widget.base:add_button
 function base.widget:add_button(button)
     if not button then return end
 
@@ -65,7 +246,8 @@ end
 
 --- Is the widget visible?
 -- @treturn boolean
--- @method get_visible
+-- @method wibox.widget.base:get_visible
+-- @hidden
 function base.widget:get_visible()
     return self._private.visible or false
 end
@@ -73,7 +255,8 @@ end
 --- Set a widget's opacity.
 -- @tparam number o The opacity to use (a number from 0 (transparent) to 1
 -- (opaque)).
--- @method set_opacity
+-- @method wibox.widget.base:set_opacity
+-- @hidden
 function base.widget:set_opacity(o)
     if o ~= self._private.opacity then
         self._private.opacity = o
@@ -83,7 +266,8 @@ end
 
 --- Get the widget's opacity.
 -- @treturn number The opacity (between 0 (transparent) and 1 (opaque)).
--- @method get_opacity
+-- @method wibox.widget.base:get_opacity
+-- @hidden
 function base.widget:get_opacity()
     return self._private.opacity
 end
@@ -91,8 +275,9 @@ end
 --- Set the widget's forced width.
 -- @tparam[opt] number width With `nil` the default mechanism of calling the
 --   `:fit` method is used.
--- @see fit_widget
--- @method set_forced_width
+-- @see wibox.widget.base:fit_widget
+-- @method wibox.widget.base:set_forced_width
+-- @hidden
 function base.widget:set_forced_width(width)
     if width ~= self._private.forced_width then
         self._private.forced_width = width
@@ -108,7 +293,8 @@ end
 -- actual size is during a `mouse::enter`, `mouse::leave` or button event.
 -- @treturn[opt] number The forced width (nil if automatic).
 -- @see fit_widget
--- @method get_forced_width
+-- @method wibox.widget.base:get_forced_width
+-- @hidden
 function base.widget:get_forced_width()
     return self._private.forced_width
 end
@@ -116,8 +302,9 @@ end
 --- Set the widget's forced height.
 -- @tparam[opt] number height With `nil` the default mechanism of calling the
 --   `:fit` method is used.
--- @see fit_widget
--- @method set_height
+-- @see wibox.widget.base:fit_widget
+-- @method wibox.widget.base:set_height
+-- @hidden
 function base.widget:set_forced_height(height)
     if height ~= self._private.forced_height then
         self._private.forced_height = height
@@ -132,7 +319,8 @@ end
 -- If there is no forced width/height, then the only way to get the widget's
 -- actual size is during a `mouse::enter`, `mouse::leave` or button event.
 -- @treturn[opt] number The forced height (nil if automatic).
--- @method get_forced_height
+-- @method wibox.widget.base:get_forced_height
+-- @hidden
 function base.widget:get_forced_height()
     return self._private.forced_height
 end
@@ -141,7 +329,8 @@ end
 --
 -- This method should be re-implemented by the relevant widgets.
 -- @treturn table children The children.
--- @method get_children
+-- @method wibox.widget.base:get_children
+-- @hidden
 function base.widget:get_children()
     return {}
 end
@@ -151,7 +340,8 @@ end
 -- The default implementation does nothing, this must be re-implemented by
 -- all layout and container widgets.
 -- @tparam table children A table composed of valid widgets.
--- @method set_children
+-- @method wibox.widget.base:set_children
+-- @hidden
 function base.widget:set_children(children) -- luacheck: no unused
     -- Nothing on purpose
 end
@@ -171,7 +361,8 @@ end
 -- *Warning*: This method it prone to stack overflow if the widget, or any of
 -- its children, contains (directly or indirectly) itself.
 -- @treturn table children The children.
--- @method get_all_children
+-- @method wibox.widget.base:get_all_children
+-- @hidden
 function base.widget:get_all_children()
     local ret = {}
     digg_children(ret, self)
@@ -197,8 +388,10 @@ function base.set_widget_common(self, widget)
 end
 
 --- Emit a signal and ensure all parent widgets in the hierarchies also
--- forward the signal. This is useful to track signals when there is a dynamic
--- set of containers and layouts wrapping the widget.
+-- forward the signal.
+--
+-- This is useful to track signals when there is a dynamic set of containers
+--   and layouts wrapping the widget.
 --
 -- Note that this function has some flaws:
 --
@@ -213,7 +406,7 @@ end
 --
 -- @tparam string signal_name
 -- @param ... Other arguments
--- @method emit_signal_recursive
+-- @method wibox.widget.base:emit_signal_recursive
 function base.widget:emit_signal_recursive(signal_name, ...)
     -- This is a convenience wrapper, the real implementation is in the
     -- hierarchy.
@@ -223,12 +416,14 @@ end
 
 --- Get the index of a widget.
 -- @tparam widget widget The widget to look for.
--- @tparam[opt] boolean recursive Also check sub-widgets?
--- @tparam[opt] widget ... Additional widgets to add at the end of the "path"
--- @treturn number The index.
+-- @tparam[opt] boolean recursive Recursively check accross the sub-widgets
+--   hierarchy.
+-- @tparam[opt] widget ... Additional widgets to add at the end of the
+--   sub-widgets hierarchy "path".
+-- @treturn number The widget index.
 -- @treturn widget The parent widget.
--- @treturn table The path between "self" and "widget".
--- @method index
+-- @treturn table The hierarchy path between "self" and "widget".
+-- @method wibox.widget.base:index
 function base.widget:index(widget, recursive, ...)
     local widgets = self:get_children()
     for idx, w in ipairs(widgets) do
@@ -577,7 +772,8 @@ end
 --
 -- See [The declarative layout system](../documentation/03-declarative-layout.md.html).
 -- @tparam table args A table containing the widget's disposition.
--- @method setup
+-- @method wibox.widget.base:setup
+-- @hidden
 function base.widget:setup(args)
     local f,ids = self.set_widget or self.add or self.set_first,{}
     local w, id = drill(ids, args)

lib/wibox/widget/checkbox.lua

@@ -9,6 +9,7 @@
 -- @author Emmanuel Lepage Valle
 -- @copyright 2010 Emmanuel Lepage Vallee
 -- @widgetmod wibox.widget.checkbox
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local color     = require( "gears.color"       )
@@ -303,10 +304,6 @@ local function new(checked, args)
     return ret
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable({}, { __call = function(_, ...) return new(...) end})
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/graph.lua

@@ -14,6 +14,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
 -- @widgetmod wibox.widget.graph
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -413,10 +414,6 @@ function graph.mt:__call(...)
     return graph.new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(graph, graph.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/imagebox.lua

@@ -21,6 +21,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @widgetmod wibox.widget.imagebox
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local lgi = require("lgi")
@@ -160,7 +161,8 @@ end
 --
 -- The image can be a file, a cairo image surface, or an rsvg handle object
 -- (see the [image property](#image)).
--- @method imagebox:set_image
+-- @method set_image
+-- @hidden
 -- @tparam image image The image to render.
 -- @treturn boolean `true` on success, `false` if the image cannot be used.
 -- @usage my_imagebox:set_image(beautiful.awesome_icon)
@@ -223,7 +225,8 @@ end
 -- Any other parameters will be passed to the clip shape function.
 --
 -- @tparam function|gears.shape clip_shape A `gears_shape` compatible shape function.
--- @method imagebox:set_clip_shape
+-- @method set_clip_shape
+-- @hidden
 -- @see gears.shape
 -- @see clip_shape
 function imagebox:set_clip_shape(clip_shape, ...)
@@ -242,7 +245,8 @@ end
 --- Should the image be resized to fit into the available space?
 -- @tparam boolean allowed If `false`, the image will be clipped, else it will
 --   be resized to fit into the available space.
--- @method imagebox:set_resize
+-- @method set_resize
+-- @hidden
 function imagebox:set_resize(allowed)
     self._private.resize_forbidden = not allowed
     self:emit_signal("widget::redraw_needed")
@@ -290,10 +294,6 @@ function imagebox.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(imagebox, imagebox.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/piechart.lua

@@ -8,6 +8,7 @@
 -- @author Emmanuel Lepage Valle
 -- @copyright 2012 Emmanuel Lepage Vallee
 -- @widgetmod wibox.widget.piechart
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local color     = require( "gears.color"       )
@@ -260,9 +261,5 @@ local function new(data_list)
     return ret
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(module, { __call = function(_, ...) return new(...) end })
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/progressbar.lua

@@ -18,6 +18,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
 -- @widgetmod wibox.widget.progressbar
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -520,10 +521,6 @@ function progressbar.mt:__call(...)
     return progressbar.new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(progressbar, progressbar.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/separator.lua

@@ -20,6 +20,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2014, 2017 Emmanuel Lepage Vallee
 -- @widgetmod wibox.widget.separator
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 local beautiful = require( "beautiful"         )
 local base      = require( "wibox.widget.base" )
@@ -215,9 +216,5 @@ local function new(args)
     return ret
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(separator, { __call = function(_, ...) return new(...) end })
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/slider.lua

@@ -7,6 +7,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2015 Grigory Mishchenko, 2016 Emmanuel Lepage Vallee
 -- @widgetmod wibox.widget.slider
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -538,10 +539,6 @@ function slider.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(slider, slider.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/systray.lua

@@ -2,6 +2,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @widgetmod wibox.widget.systray
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local wbase = require("wibox.widget.base")
@@ -224,10 +225,6 @@ function systray.mt:__call(...)
     return instance
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(systray, systray.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/textbox.lua

@@ -1,10 +1,12 @@
 ---------------------------------------------------------------------------
 --
 --@DOC_wibox_widget_defaults_textbox_EXAMPLE@
+--
 -- @author Uli Schlachter
 -- @author dodo
 -- @copyright 2010, 2011 Uli Schlachter, dodo
 -- @widgetmod wibox.widget.textbox
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local base = require("wibox.widget.base")
@@ -373,10 +375,6 @@ function textbox.mt.__call(_, ...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(textbox, textbox.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/textclock.lua

@@ -4,6 +4,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
 -- @widgetmod wibox.widget.textclock
+-- @supermodule wibox.widget.textbox
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -126,10 +127,6 @@ function textclock.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(textclock, textclock.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80