From 4dbc83fa7d7ba1ce985e3c5f120508fd8aa666a7 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 27 Oct 2019 15:39:23 -0400 Subject: [PATCH] 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 | 29 +++++++++++++++++------------ docs/ldoc.ltp | 29 +++++++++++++++++++++++++---- lib/awful/button.lua | 2 +- lib/awful/key.lua | 2 +- mouse.c | 2 +- 5 files changed, 45 insertions(+), 19 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 120ba85c4..76508b46e 100644 --- a/docs/config.ld +++ b/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, - constructorfct = true, - staticfct = true, - deprecated = true, - field = true, + ["function"] = true, + constructorfct = true, + constructorfct2 = true, + staticfct = true, + deprecated = true, + field = true, } -- Add the arguments. local add_args = { - constructorfct = true, - staticfct = true, + constructorfct = 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, - constructorfct = true, - staticfct = true, - method = true, - deprecated = true, + ["function"] = true, + constructorfct = true, + constructorfct2 = true, + staticfct = true, + method = true, + deprecated = true, } custom_display_name_handler = function(item, default_handler) diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index ee8f6534f..eebb6b436 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -49,22 +49,28 @@

Contents

# 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 -

$(kind)

+# if not kind:match("^ldoc_skip") then +

$(kind)dasdasd

# 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 + +# end

$(kind)

+# 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 @@ # end -- for items -
$(M(item.summary,item))
+# last_kind = kind #end -- for kinds +

@@ -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 + +# end

$(kind)

+# end $(M(module.kinds:get_section_description(kind),nil)) # if kitem then # if has_description then @@ -169,7 +187,9 @@ 
$(ldoc.prettify(kitem.usage[1]))
# end # end +# if not kind:match("^ldoc_skip") then
+# end # for item in items() do
@@ -289,8 +309,9 @@ # end -- for items -
+# last_kind = kind # end -- for kinds + # else -- if module; project-level contents diff --git a/lib/awful/button.lua b/lib/awful/button.lua index b59303f05..aadf7c7ab 100644 --- a/lib/awful/button.lua +++ b/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 diff --git a/lib/awful/key.lua b/lib/awful/key.lua index 5826a7c97..1852e7d97 100644 --- a/lib/awful/key.lua +++ b/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 diff --git a/mouse.c b/mouse.c index c446243a9..42d0b382d 100644 --- a/mouse.c +++ b/mouse.c @@ -57,7 +57,7 @@ * * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou - * @coreclassmod mouse + * @inputmodule mouse */ #include "mouse.h"