doc: Modify the template to allow merging sections.

It might not be the most pretty of change, but it works. With this
change, it is possible to have multiple "things" in the "same"
section having the "same" name.

This allows for C/C++ style functions with the same name but different
signatures. Lua doesn't handle this well, so it should usually be
avoided. However, constructors might be a valid exception. Most older
widget (and object) constructors have multiple random argument while
newer one use `args`. Deprecating the old ones for the sake of
standardization might be a bit too much for users upgrading from v3.5.

Given the only reason all of those deprecation would happen is because
"its pretty that way", then lets allow 2 constructors and avoid outrage.

docs/config.ld

@@ -54,6 +54,7 @@ tparam_alias('screen_or_idx', 'screen|int')
 
 -- The first stereotype are the constructors.
 new_type("constructorfct", "Constructors", false, "Parameters")
+new_type("constructorfct2", "ldoc_skip", false, "Parameters")
 -- Hack to get the functions on top of the signals and properties
 new_type("function", "Functions", false, "Parameters")
 -- For "classes", use an explicit type for static functions. This allows
@@ -100,6 +101,7 @@ sort_modules=true
 
 -- Add more project level (left side index) types.
 new_type("coreclassmod", "Core_components"  , true)
+new_type("inputmodule" , "Input handling"   , true)
 new_type("widgetmod"   , "Widgets"   , true)
 new_type("containermod", "Widget_containers", true)
 new_type("layoutmod"   , "Widget_layouts"   , true)
@@ -264,17 +266,19 @@ local coreclassmap = {
 
 -- Add the full module name in front.
 local add_mod = {
-    ["function"]   = true,
+    ["function"]    = true,
-    constructorfct = true,
+    constructorfct  = true,
-    staticfct      = true,
+    constructorfct2 = true,
-    deprecated     = true,
+    staticfct       = true,
-    field          = true,
+    deprecated      = true,
+    field           = true,
 }
 
 -- Add the arguments.
 local add_args = {
-    constructorfct = true,
+    constructorfct  = true,
-    staticfct      = true,
+    constructorfct2 = true,
+    staticfct       = true,
 }
 
 -- Add a type column to the summary and type field in the description.
@@ -287,11 +291,12 @@ local display_type = {
 
 -- Show return values.
 local show_return = {
-    ["function"]   = true,
+    ["function"]    = true,
-    constructorfct = true,
+    constructorfct  = true,
-    staticfct      = true,
+    constructorfct2 = true,
-    method         = true,
+    staticfct       = true,
-    deprecated     = true,
+    method          = true,
+    deprecated      = true,
 }
 
 custom_display_name_handler = function(item, default_handler)

docs/ldoc.ltp

@@ -49,22 +49,28 @@
 <h2>Contents</h2>
 <ul>
 # for kind,items in module.kinds() do
+#  if not kind:match("^ldoc_skip") then
 <li><a href="#$(no_spaces(kind))">$(kind)</a></li>
 # end
+# end
 </ul>
 # end
 
 
 # if ldoc.no_summary and module and not ldoc.one then -- bang out the functions on the side
 # for kind, items in module.kinds() do
-<h2>$(kind)</h2>
+#  if not kind:match("^ldoc_skip") then
+<h2>$(kind)dasdasd</h2>
 <ul class="nowrap">
+#  end
 # for item in items() do
     <li><a href="#$(item.name)">$(display_name(item))</a></li>
 # end
+#  if not kind:match("^ldoc_skip") then
 </ul>
 # end
 # end
+# end
 # -------- contents of project ----------
 # local this_mod = module and module.name
 # for kind, mods, type in ldoc.kinds() do
@@ -125,9 +131,15 @@
 
 # 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
+#  if not kind:match("^ldoc_skip") then
+#   if last_kind ~= "" then
+</table>
+#   end
 <h2><a href="#$(no_spaces(kind))">$(kind)</a></h2>
 <table class="function_list">
+#  end
 #  for item in items() do
 #   local dn = display_name(item)
 #   if item.sanitize_type then item.sanitize_type(item, ldoc) end
@@ -141,8 +153,9 @@
       <td class="summary">$(M(item.summary,item))</td>
     </tr>
 #  end -- for items
-</table>
+# last_kind = kind
 #end -- for kinds
+</table>
 
 <br/>
 <br/>
@@ -152,11 +165,16 @@
 # --- currently works for both Functions and Tables. The params field either contains
 # --- function parameters or table fields.
 # local show_return = not ldoc.no_return_or_parms
-# local show_parms = show_return
+# local show_parms, last_kind = show_return, ""
 # for kind, items in module.kinds() do
 #   local kitem = module.kinds:get_item(kind)
 #   local has_description = kitem and ldoc.descript(kitem) ~= ""
+#   if not kind:match("^ldoc_skip") then
+#    if last_kind ~= "" then
+</dl>
+#    end
     <h2 class="section-header $(has_description and 'has-description')"><a name="$(no_spaces(kind))"></a>$(kind)</h2>
+#   end
     $(M(module.kinds:get_section_description(kind),nil))
 #   if kitem then
 #       if has_description then
@@ -169,7 +187,9 @@
             <pre class="example">$(ldoc.prettify(kitem.usage[1]))</pre>
 #        end
 #   end
+#  if not kind:match("^ldoc_skip") then
     <dl class="function">
+#  end
 #  for item in items() do
     <dt>
     <a name = "$(item.name)"></a>
@@ -289,8 +309,9 @@
 
 </dd>
 # end -- for items
-</dl>
+#  last_kind = kind
 # end -- for kinds
+</dl>
 
 # else -- if module; project-level contents
 

lib/awful/button.lua

@@ -3,7 +3,7 @@
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
--- @classmod awful.button
+-- @inputmodule awful.button
 ---------------------------------------------------------------------------
 
 -- Grab environment we need

lib/awful/key.lua

@@ -3,7 +3,7 @@
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
--- @classmod awful.key
+-- @inputmodule awful.key
 ---------------------------------------------------------------------------
 
 -- Grab environment we need

mouse.c

@@ -57,7 +57,7 @@
  *
  * @author Julien Danjou <julien@danjou.info>
  * @copyright 2008-2009 Julien Danjou
- * @coreclassmod mouse
+ * @inputmodule mouse
  */
 
 #include "mouse.h"