Bug 383871 - [luadocumentor] @usage is not generated correctly

5 files changed, 59 insertions, 45 deletions

diff --git a/libraries/doctemplates/template/file.lua b/libraries/doctemplates/template/file.lua
index 2c33482..2439353 100644
--- a/libraries/doctemplates/template/file.lua
+++ b/libraries/doctemplates/template/file.lua
@@ -15,7 +15,7 @@ return[[#
 # -- Module name

 # --

 # if _file.name then

-   <h1>Module <code>$(_file.name)</code></h1>

+   <h$(i)>Module <code>$(_file.name)</code></h$(i)>

 # end

 # --

 # -- Descriptions

@@ -29,11 +29,8 @@ return[[#
 # --

 # -- Handle "@usage" special tag

 # --

-#if _file.metadata and _file.metadata.usage and #_file.metadata.usage > 0 then

-	<h2>Usage examples</h2>

-#	for _, usage in ipairs( _file.metadata.usage ) do

-		<pre><code>$( securechevrons(usage.description) )</code></pre>

-#	end

+#if _file.metadata and _file.metadata.usage then

+	$( applytemplate(_file.metadata.usage, i+1) )

 #end

 # --

 # -- Show quick description of current type

@@ -41,7 +38,7 @@ return[[#
 # 

 # -- show quick description for globals

 # if not isempty(_file.globalvars) then

-	<h2>Global(s)</h2>

+	<h$(i+1)>Global(s)</h$(i+1)>

 	<table class="function_list">

 #	for _, item in sortedpairs(_file.globalvars) do

 		<tr>

@@ -65,20 +62,18 @@ return[[#
 #	end

 #

 # -- show quick description type exposed by module

-# if currenttype then

-	<a id="$(anchor(currenttype))" />

-	<h2>Type <code>$(currenttype.name)</code></h2>

-	$( applytemplate(currenttype, 'index') )

+# if currenttype then
+	<h$(i+1)><a id="$(anchor(currenttype))" >Type <code>$(currenttype.name)</code></a></h$(i+1)>

+	$( applytemplate(currenttype, i+2, 'index') )
 # end

 # --

 # -- Show quick description of other types

 # --

 # if _file.types then

 #	for name, type in sortedpairs( _file.types ) do

-#		if type ~= currenttype and type.tag == 'recordtypedef' then

-			<a id="$(anchor(type))" />

-			<h2>Type <code>$(name)</code></h2>

-			$( applytemplate(type, 'index') )

+#		if type ~= currenttype and type.tag == 'recordtypedef' then
+			<h$(i+1)><a id="$(anchor(type))">Type <code>$(name)</code></a></h$(i+1)>

+			$( applytemplate(type, i+2, 'index') )
 #		end

 #	end

 # end

@@ -86,17 +81,17 @@ return[[#
 # -- Long description of globals

 # --

 # if not isempty(_file.globalvars) then

-	<h2>Global(s)</h2>

+	<h$(i+1)>Global(s)</h$(i+1)>

 #	for name, item in sortedpairs(_file.globalvars) do

-		$( applytemplate(item) )

+		$( applytemplate(item, i+2) )

 #	end

 # end

 # --

 # -- Long description of current type

 # --

 # if currenttype then

-	<h2>Type <code>$(currenttype.name)</code></h2>

-	$( applytemplate(currenttype) )

+	<h$(i+1)>Type <code>$(currenttype.name)</code></h$(i+1)>

+	$( applytemplate(currenttype, i+2) )

 # end

 # --

 # -- Long description of other types

@@ -104,8 +99,8 @@ return[[#
 # if not isempty( _file.types ) then

 #	for name, type in sortedpairs( _file.types ) do

 #		if type ~= currenttype  and type.tag == 'recordtypedef' then

-			<h2>Type <code>$(name)</code></h2>

-			$( applytemplate(type) )

+			<h$(i+1)>Type <code>$(name)</code></h$(i+1)>

+			$( applytemplate(type, i+2) )

 #		end

 #	end

 # end

diff --git a/libraries/doctemplates/template/item.lua b/libraries/doctemplates/template/item.lua
index 54ad5e9..034b885 100644
--- a/libraries/doctemplates/template/item.lua
+++ b/libraries/doctemplates/template/item.lua
@@ -66,7 +66,7 @@ return
 #
 #	-- List parameters
 #	if paramcount > 0 then
-		<h3>Parameter$( paramcount > 1 and 's' )</h3>
+		<h$(i)>Parameter$( paramcount > 1 and 's' )</h$(i)>
 		<ul>
 #		for position, param in ipairs( fdef.params ) do
 #			if not (position == 1 and param.name == 'self') then
@@ -82,7 +82,7 @@ return
 #	-- Describe returns types
 #	--
 #	if fdef and #fdef.returns > 0 then
-		<h3>Return value$(#fdef.returns > 1 and 's')</h3>
+		<h$(i)>Return value$(#fdef.returns > 1 and 's')</h$(i)>
 #		--
 #		-- Format nice type list
 #		--
@@ -132,19 +132,7 @@ return
 #-- Show usage samples
 #--
 #if _item.metadata and _item.metadata.usage then
-	<h3>Usage:</h3>
-	<ul>
-#	if #_item.metadata.usage > 1 then
-#		-- Loop over several usage description
-#		for _, usage in ipairs(_item.metadata.usage) do
-			 <li><pre class="example">$( securechevrons(usage.description) )</pre></li>
-#		end
-# else
-#		-- Show unique usage sample
-#		local usage = _item.metadata.usage[1]
-		<pre class="example">$( securechevrons(usage.description) )</pre>
-# end
-  </ul>
+	$( applytemplate(_item.metadata.usage, i) )
 #end
 </dd>
 </dl>]]
diff --git a/libraries/doctemplates/template/recordtypedef.lua b/libraries/doctemplates/template/recordtypedef.lua
index 24ad3aa..fb16469 100644
--- a/libraries/doctemplates/template/recordtypedef.lua
+++ b/libraries/doctemplates/template/recordtypedef.lua
@@ -24,17 +24,14 @@ return [[#
 #-- Describe usage
 #--
 #if _recordtypedef.metadata and _recordtypedef.metadata.usage then
-	<h2>Usage examples</h2>
-#	for _, usage in ipairs(_recordtypedef.metadata.usage) do
-		<pre><code>$( securechevrons(usage.description) )</code></pre>
-#	end
+	$( applytemplate(_recordtypedef.metadata.usage, i) )
 #end
 # --
 # -- Describe type fields
 # --
 #if not isempty( _recordtypedef.fields ) then
-	<h3>Field(s)</h3>
+	<h$(i)>Field(s)</h$(i)>
 #	for name, item in sortedpairs( _recordtypedef.fields ) do
-		$( applytemplate(item) )
+		$( applytemplate(item, i) )
 #	end
 #end ]]
diff --git a/libraries/doctemplates/template/usage.lua b/libraries/doctemplates/template/usage.lua
new file mode 100644
index 0000000..bb74dd0
--- a/dev/null
+++ b/libraries/doctemplates/template/usage.lua
@@ -0,0 +1,33 @@
+--------------------------------------------------------------------------------
+--  Copyright (c) 2012 Sierra Wireless.
+--  All rights reserved. This program and the accompanying materials
+--  are made available under the terms of the Eclipse Public License v1.0
+--  which accompanies this distribution, and is available at
+--  http://www.eclipse.org/legal/epl-v10.html
+--
+--  Contributors:
+--       Marc AUBRY <maubry@sierrawireless.com>
+--           - initial API and implementation
+--------------------------------------------------------------------------------
+return[[#
+#--
+#-- Show usage samples
+#--
+#if _usage then
+#	if #_usage > 1 then
+#		-- Show all usages
+		<h$(i)>Usages:</h$(i)>
+		<ul>
+#		-- Loop over several usage description
+#		for _, usage in ipairs(_usage) do
+			<li><pre class="example"><code>$( securechevrons(usage.description) )</code></pre></li>
+#		end
+		</ul>
+#	elseif #_usage == 1 then
+#		-- Show unique usage sample
+		<h$(i)>Usage:</h$(i)>
+#		local usage = _usage[1]
+		<pre class="example"><code>$( securechevrons(usage.description) )</code></pre>
+#	end
+#end
+#]]
diff --git a/libraries/templateengine/templateengine.lua b/libraries/templateengine/templateengine.lua
index 81874e1..a3f9735 100644
--- a/libraries/templateengine/templateengine.lua
+++ b/libraries/templateengine/templateengine.lua
@@ -20,9 +20,9 @@ local pltemplate = require 'pl.template'
 local markdown = require 'markdown'
 
 -- apply template to the given element
-function M.applytemplate(elem,templatetype)
+function M.applytemplate(elem, ident, templatetype)
 	-- define environment
-	local env = M.getenv(elem,templatetype)
+	local env = M.getenv(elem, ident)
 
 	-- load template
 	local template = M.gettemplate(elem,templatetype)
@@ -44,12 +44,13 @@ function M.applytemplate(elem,templatetype)
 end
 
 -- get the a new environment for this element
-function M.getenv(elem)
+function M.getenv(elem, ident)
 	local currentenv ={}
 	for k,v in pairs(M.env) do currentenv[k] = v end
 	if elem and elem.tag then
 		currentenv['_'..elem.tag]= elem
 	end
+	currentenv['i']= ident or 1
 	return currentenv
 end