From af3b194a31a645bff07cc3271c85ddc61dc29ac6 Mon Sep 17 00:00:00 2001
From: Aire-One <erwan.maugere@gmail.com>
Date: Sun, 28 Mar 2021 18:19:08 +0200
Subject: [PATCH] doc(@hidden;ldoc.ltp): Add ldoc tag to hide item

Add a new ldoc tag `@hidden`. This tag allows us to keep documentation
for magic methods (e.g. `wibox.widget.base:get_visible`) but prevent
it from being part of the documentation used by final users.
---
 docs/config.ld | 11 ++++++++++-
 docs/ldoc.ltp  | 10 +++++-----
 2 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/docs/config.ld b/docs/config.ld
index 7894127d..9b6911d9 100644
--- a/docs/config.ld
+++ b/docs/config.ld
@@ -462,7 +462,16 @@ add_custom_tag {
 -- @supermodule supermodule
 add_custom_tag {
     name = "supermodule",
-    hiden = true,
+    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
 }
 
diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp
index 067a94fd..8425bfa3 100644
--- a/docs/ldoc.ltp
+++ b/docs/ldoc.ltp
@@ -72,7 +72,7 @@
 # for kind,items in module.kinds() do
 #     local myitems = {}
 #     for item in items() do
-#         myitems[#myitems + 1] = item
+#       myitems[#myitems + 1] = item
 #      end
 #     all_module_kinds[#all_module_kinds + 1] = { kind = kind,  items = myitems }
 # end
@@ -257,7 +257,7 @@
 <h2><a href="#$(no_spaces(kind))">$(kind)</a></h2>
 <table class="function_list">
 #  end
-#  for item in iter(k.items) do
+#  for item in iter(k.items) do if not item.tags.hidden then
 #   local dn = display_name(item)
 #   local inherited = item.inherited or (item.baseclass ~= module.name)
 #   if item.sanitize_type then item.sanitize_type(item, ldoc) end
@@ -280,7 +280,7 @@
       </td>
 #   end
     </tr>
-#  end -- for items
+#  end end -- for items
 # last_kind = kind
 #end -- for kinds
 </table>
@@ -319,7 +319,7 @@
 #  if not kind:match("^ldoc_skip") then
     <dl class="function">
 #  end
-#  for item in iter(k.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>
@@ -479,7 +479,7 @@
     </span>
 
 </dd>
-# end -- for items
+# end end -- for items
 #  last_kind = kind
 # end -- for kinds
 </dl>