From 7528812494f1408d3f6db6deb8455d56362c05b6 Mon Sep 17 00:00:00 2001
From: Jo-Philipp Wich <jow@openwrt.org>
Date: Sat, 9 Aug 2008 18:38:16 +0000
Subject: [PATCH] * luci/contrib:	added support for constants
 documentation in luadoc

---
 .../luadoc/lua/luadoc/doclet/html/constant.lp | 28 +++++++++++
 .../luadoc/lua/luadoc/doclet/html/module.lp   | 15 +++++-
 contrib/luadoc/lua/luadoc/taglet/standard.lua | 46 +++++++++++++++++++
 3 files changed, 87 insertions(+), 2 deletions(-)
 create mode 100644 contrib/luadoc/lua/luadoc/doclet/html/constant.lp

diff --git a/contrib/luadoc/lua/luadoc/doclet/html/constant.lp b/contrib/luadoc/lua/luadoc/doclet/html/constant.lp
new file mode 100644
index 0000000000..2e35392ad6
--- /dev/null
+++ b/contrib/luadoc/lua/luadoc/doclet/html/constant.lp
@@ -0,0 +1,28 @@
+<%
+if module_doc then
+	from = "modules/"..module_doc.name
+elseif file_doc then
+	from = "files/.."..file_doc.name
+else
+	from = ""
+end
+%>
+
+<dt><%=const.private and "local " or ""%><a name="<%=const.name%>"></a><strong><%=const.name:gsub(".+%.","")%></strong></dt>
+<dd>
+<%=const.description or ""%>
+
+<%if type(const.see) == "string" then %>
+<h3>See also:</h3>
+	<a href="<%=const.see%>"><%=const.see%></a>
+<%elseif type(const.see) == "table" and #const.see > 0 then %>
+<h3>See also:</h3>
+<ul>
+	<%for i = 1, #const.see do%>
+	<li><a href="<%=luadoc.doclet.html.symbol_link(const.see[i], doc, module_doc, file_doc, from)%>">
+		<%=const.see[i]:gsub(".+%.","")%>
+	</a>
+	<%end%>
+</ul
+<%end%>
+</dd>
diff --git a/contrib/luadoc/lua/luadoc/doclet/html/module.lp b/contrib/luadoc/lua/luadoc/doclet/html/module.lp
index 5c2dfa072d..11e2f118be 100644
--- a/contrib/luadoc/lua/luadoc/doclet/html/module.lp
+++ b/contrib/luadoc/lua/luadoc/doclet/html/module.lp
@@ -45,6 +45,19 @@
 <p><small><b>Release:</b> <%=module_doc.release%></small></p>
 <%end%>
 
+<%if #module_doc.constants > 0 then %>
+<h2>Constants</h2>
+<table class="function_list">
+<%for _, const_name in ipairs(module_doc.constants) do
+  local const_data = module_doc.constants[const_name]%>
+	<tr>
+	<td class="name" nowrap><code><%=const_data.private and "local " or ""%><%=(const_name:gsub(".+%.",""))%></code></td>
+	<td class="summary"><%=const_data.summary%></td>
+	</tr>
+<%end%>
+</table>
+<%end%>
+
 <%if #module_doc.functions > 0 then %>
 <h2>Functions</h2>
 <table class="function_list">
@@ -75,7 +88,6 @@
 <br/>
 <br/>
 
-
 <%if #module_doc.functions > 0 then%>
 <h2><a name="functions"></a>Functions</h2>
 <dl class="function">
@@ -85,7 +97,6 @@
 </dl>
 <%end%>
 
-
 <%if #module_doc.tables > 0 then%>
 <h2><a name="tables"></a>Tables</h2>
 <dl class="table">
diff --git a/contrib/luadoc/lua/luadoc/taglet/standard.lua b/contrib/luadoc/lua/luadoc/taglet/standard.lua
index c02bc98bef..f55ea72042 100644
--- a/contrib/luadoc/lua/luadoc/taglet/standard.lua
+++ b/contrib/luadoc/lua/luadoc/taglet/standard.lua
@@ -96,6 +96,38 @@ local function check_module (line, currentmodule)
 	return currentmodule
 end
 
+-- Patterns for constant recognition
+local constant_patterns = {
+	"^()%s*([A-Z][A-Z0-9_]*)%s*=",
+	"^%s*(local%s)%s*([A-Z][A-Z0-9_]*)%s*=",
+}
+
+-------------------------------------------------------------------------------
+-- Checks if the line contains a constant definition
+-- @param line string with line text
+-- @return constant information or nil if no constant definition found
+
+local function check_constant (line)
+	line = util.trim(line)
+
+	local info = table.foreachi(constant_patterns, function (_, pattern)
+		local r, _, l, id = string.find(line, pattern)
+		if r ~= nil then
+			return {
+				name = id,
+				private = (l == "local"),
+			}
+		end
+	end)
+
+	-- TODO: remove these assert's?
+	if info ~= nil then
+		assert(info.name, "constant name undefined")
+	end
+
+	return info
+end
+
 -------------------------------------------------------------------------------
 -- Extracts summary information from a description. The first sentence of each
 -- doc comment should be a summary sentence, containing a concise but complete
@@ -172,11 +204,16 @@ local function parse_comment (block, first_line, modulename)
 	if code ~= nil then
 		local func_info = check_function(code)
 		local module_name = check_module(code)
+		local const_info = check_constant(code)
 		if func_info then
 			block.class = "function"
 			block.name = func_info.name
 			block.param = func_info.param
 			block.private = func_info.private
+		elseif const_info then
+			block.class = "constant"
+			block.name = const_info.name
+			block.private = const_info.private
 		elseif module_name then
 			block.class = "module"
 			block.name = module_name
@@ -403,6 +440,15 @@ function parse_file (filepath, doc, handle, prev_line, prev_block, prev_modname)
 				doc.modules[modulename].tables[t.name] = t
 			end
 		end
+
+		-- make constants table
+		doc.modules[modulename].constants = {}
+		for c in class_iterator(blocks, "constant")() do
+			if c and c.name then
+				table.insert(doc.modules[modulename].constants, c.name)
+				doc.modules[modulename].constants[c.name] = c
+			end
+		end
 	end
 
 	if filepath then
-- 
2.30.2