* luci/contrib: added support for constants documentation in luadoc

diff --git a/contrib/luadoc/lua/luadoc/doclet/html/constant.lp b/contrib/luadoc/lua/luadoc/doclet/html/constant.lp
new file mode 100644 (file)
index 0000000..2e35392
--- /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 5c2dfa0..11e2f11 100644 (file)
--- 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%>
 
 <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">
 <%if #module_doc.functions > 0 then %>
 <h2>Functions</h2>
 <table class="function_list">


@@ -75,7 +88,6 @@
 <br/>
 <br/>
 
 <br/>
 <br/>
 

-

 <%if #module_doc.functions > 0 then%>
 <h2><a name="functions"></a>Functions</h2>
 <dl class="function">
 <%if #module_doc.functions > 0 then%>
 <h2><a name="functions"></a>Functions</h2>
 <dl class="function">


@@ -85,7 +97,6 @@
 </dl>
 <%end%>
 
 </dl>
 <%end%>
 

-

 <%if #module_doc.tables > 0 then%>
 <h2><a name="tables"></a>Tables</h2>
 <dl class="table">
 <%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 c02bc98..f55ea72 100644 (file)
--- 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
 
        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
 -------------------------------------------------------------------------------
 -- 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)
        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
                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
                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
                                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
        end
 
        if filepath then