From: Jo-Philipp Wich <jow@openwrt.org>
Date: Sat, 9 Aug 2008 17:41:01 +0000 (+0000)
Subject: * luci/contrib:	implemented "@cstyle" tag in luadoc to tell whether a "module" is... 
X-Git-Tag: 0.8.0~481
X-Git-Url: https://git.archive.openwrt.org/?p=project%2Fluci.git;a=commitdiff_plain;h=fa2d17a3f913c4e362fe8d16c536c0ecf800158b

* luci/contrib:	implemented "@cstyle" tag in luadoc to tell whether a "module" is a class or an object instance; changed templates to use instance:function() notation for instances and function() notation for class members.
---

diff --git a/contrib/luadoc/lua/luadoc/doclet/html/function.lp b/contrib/luadoc/lua/luadoc/doclet/html/function.lp
index aa0e25b14..afc645b07 100644
--- a/contrib/luadoc/lua/luadoc/doclet/html/function.lp
+++ b/contrib/luadoc/lua/luadoc/doclet/html/function.lp
@@ -8,7 +8,7 @@ else
 end
 %>
 
-<dt><%=func.private and "local " or ""%><a name="<%=func.name%>"></a><strong><%=func.name%></strong>&nbsp;(<%=table.concat(func.param, ", ")%>)</dt>
+<dt><%=func.private and "local " or ""%><a name="<%=func.name%>"></a><strong><%=(oop and func.name:gsub("%.",":") or func.name:gsub(".+%.",""))%></strong>&nbsp;(<%=table.concat(func.param, ", ")%>)</dt>
 <dd>
 <%=func.description or ""%>
 
@@ -56,9 +56,9 @@ end
 <ul>
 	<%for i = 1, #func.see do%>
 	<li><a href="<%=luadoc.doclet.html.symbol_link(func.see[i], doc, module_doc, file_doc, from)%>">
-		<%=func.see[i]%>
+		<%=(oop and func.see[i]:gsub("%.",":") or func.see[i]:gsub(".+%.",""))%>
 	</a>
 	<%end%>
-</ul>
+</ul
 <%end%>
 </dd>
diff --git a/contrib/luadoc/lua/luadoc/doclet/html/module.lp b/contrib/luadoc/lua/luadoc/doclet/html/module.lp
index 6dca9a9ad..5c2dfa072 100644
--- a/contrib/luadoc/lua/luadoc/doclet/html/module.lp
+++ b/contrib/luadoc/lua/luadoc/doclet/html/module.lp
@@ -20,12 +20,13 @@
 
 <div id="navigation">
 <%=luadoc.doclet.html.include("menu.lp", { doc=doc, module_doc=module_doc })%>
+<% oop = ( module_doc.doc[1].cstyle == "instance" ) and true or false %>
 
 </div><!-- id="navigation" -->
 
 <div id="content">
 
-<h1>Module <code><%=module_doc.name%></code></h1>
+<h1><%=( oop and "Object Instance" or "Class" )%> <code><%=module_doc.name%></code></h1>
 
 <p><%=module_doc.description%></p>
 <%if module_doc.author then%>
@@ -44,13 +45,13 @@
 <p><small><b>Release:</b> <%=module_doc.release%></small></p>
 <%end%>
 
-<%if #module_doc.functions > 0 then%>
+<%if #module_doc.functions > 0 then %>
 <h2>Functions</h2>
 <table class="function_list">
 <%for _, func_name in ipairs(module_doc.functions) do
   local func_data = module_doc.functions[func_name]%>
 	<tr>
-	<td class="name" nowrap><%=func_data.private and "local " or ""%><a href="#<%=func_name%>"><%=func_name%></a>&nbsp;(<%=table.concat(module_doc.functions[func_name].param, ", ")%>)</td>
+	<td class="name" nowrap><%=func_data.private and "local " or ""%><a href="#<%=func_name%>"><%=(oop and func_name:gsub("%.",":") or func_name:gsub(".+%.",""))%></a>&nbsp;(<%=table.concat(module_doc.functions[func_name].param, ", ")%>)</td>
 	<td class="summary"><%=module_doc.functions[func_name].summary%></td>
 	</tr>
 <%end%>
@@ -79,7 +80,7 @@
 <h2><a name="functions"></a>Functions</h2>
 <dl class="function">
 <%for _, func_name in ipairs(module_doc.functions) do%>
-<%=luadoc.doclet.html.include("function.lp", { doc=doc, module_doc=module_doc, func=module_doc.functions[func_name] })%>
+<%=luadoc.doclet.html.include("function.lp", { doc=doc, module_doc=module_doc, func=module_doc.functions[func_name], oop=oop })%>
 <%end%>
 </dl>
 <%end%>
@@ -103,6 +104,6 @@
 	<p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
 </div> <!-- id="about" -->
 
-</div> <!-- id="container" -->	
+</div> <!-- id="container" -->
 </body>
 </html>
diff --git a/contrib/luadoc/lua/luadoc/taglet/standard/tags.lua b/contrib/luadoc/lua/luadoc/taglet/standard/tags.lua
index 980514c5f..d03df82df 100644
--- a/contrib/luadoc/lua/luadoc/taglet/standard/tags.lua
+++ b/contrib/luadoc/lua/luadoc/taglet/standard/tags.lua
@@ -23,7 +23,7 @@ local function author (tag, block, text)
 end
 
 -------------------------------------------------------------------------------
--- Set the class of a comment block. Classes can be "module", "function", 
+-- Set the class of a comment block. Classes can be "module", "function",
 -- "table". The first two classes are automatic, extracted from the source code
 
 local function class (tag, block, text)
@@ -32,6 +32,12 @@ end
 
 -------------------------------------------------------------------------------
 
+local function cstyle (tag, block, text)
+	block[tag] = text
+end
+
+-------------------------------------------------------------------------------
+
 local function copyright (tag, block, text)
 	block[tag] = text
 end
@@ -52,7 +58,7 @@ local function field (tag, block, text)
 
 	local _, _, name, desc = string.find(text, "^([_%w%.]+)%s+(.*)")
 	assert(name, "field name not defined")
-	
+
 	table.insert(block[tag], name)
 	block[tag][name] = desc
 end
@@ -65,7 +71,7 @@ local function name (tag, block, text)
 	if block[tag] and block[tag] ~= text then
 		luadoc.logger:error(string.format("block name conflict: `%s' -> `%s'", block[tag], text))
 	end
-	
+
 	block[tag] = text
 end
 
@@ -120,12 +126,12 @@ end
 local function see (tag, block, text)
 	-- see is always an array
 	block[tag] = block[tag] or {}
-	
+
 	-- remove trailing "."
 	text = string.gsub(text, "(.*)%.$", "%1")
-	
-	local s = util.split("%s*,%s*", text)			
-	
+
+	local s = util.split("%s*,%s*", text)
+
 	table.foreachi(s, function (_, v)
 		table.insert(block[tag], v)
 	end)
@@ -149,6 +155,7 @@ end
 local handlers = {}
 handlers["author"] = author
 handlers["class"] = class
+handlers["cstyle"] = cstyle
 handlers["copyright"] = copyright
 handlers["description"] = description
 handlers["field"] = field