From c52f7cfd8fece25a3b3d5b1692dff2033b493285 Mon Sep 17 00:00:00 2001
From: Robin Gareus <robin@gareus.org>
Date: Tue, 12 Apr 2016 13:53:02 +0200
Subject: [PATCH] update luadoc tools

---
 tools/doxy2json/ardourdoc.sh |  2 +-
 tools/fmt-luadoc.php         | 37 +++++++++++++++++++++++++++++++++++-
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/tools/doxy2json/ardourdoc.sh b/tools/doxy2json/ardourdoc.sh
index 870c1e53c3..b9e7db8ff0 100755
--- a/tools/doxy2json/ardourdoc.sh
+++ b/tools/doxy2json/ardourdoc.sh
@@ -10,7 +10,7 @@ TMPFILE=`mktemp`
 trap 'rm -f $TMPFILE' exit SIGINT SIGTERM
 
 echo "# analyzing source.. -> $TMPFILE"
-./tools/doxy2json/doxy2json -j 4 \
+time ./tools/doxy2json/doxy2json -j 4 \
 	$LLVMINCLUDE \
 	-D PACKAGE=\"doc\" \
 	-D PROGRAM_NAME=\"Ardour\" -D PROGRAM_VERSION=\"4\" -D LOCALEDIR=\"/\" \
diff --git a/tools/fmt-luadoc.php b/tools/fmt-luadoc.php
index e541f0cf98..530a4d8c48 100755
--- a/tools/fmt-luadoc.php
+++ b/tools/fmt-luadoc.php
@@ -34,7 +34,9 @@ foreach (json_decode ($json, true) as $b) {
 		if (isset ($b['version'])) { $ardourversion = $b['version']; }
 		continue;
 	}
+	# reserved lua words
 	$b ['lua'] = preg_replace ('/:_end/', ':end', $b ['lua']);
+	$b ['lua'] = preg_replace ('/:_type/', ':type', $b ['lua']);
 	$b ['ldec'] = preg_replace ('/ const/', '', preg_replace ('/ const&/', '', $b['decl']));
 	if (isset ($b['ret'])) {
 		$b['ret'] = preg_replace ('/ const/', '', preg_replace ('/ const&/', '', $b['ret']));
@@ -371,7 +373,6 @@ foreach ($doc as $b) {
 	case "Weak/Shared Pointer Function":
 	case "Weak/Shared Pointer Function RefReturn":
 	case "Weak/Shared Null Check":
-	case "Weak/Shared Pointer Cast":
 	case "Static Member Function":
 		checkclass ($b);
 		$classlist[luafn2class ($b['lua'])]['func'][] = array (
@@ -383,6 +384,17 @@ foreach ($doc as $b) {
 			'cand' => canonical_decl ($b)
 		);
 		break;
+	case "Weak/Shared Pointer Cast":
+		checkclass ($b);
+		$classlist[luafn2class ($b['lua'])]['cast'][] = array (
+			'bind' => $b,
+			'name' => $b['lua'],
+			'args' => decl2args ($b['ldec']),
+			'ret'  => arg2lua ($b['ret']),
+			'ref'  => (strpos ($b['type'], "RefReturn") !== false),
+			'cand' => canonical_decl ($b)
+		);
+		break;
 	case "Constant/Enum":
 	case "Constant/Enum Member":
 		# already handled -> $consts
@@ -644,6 +656,23 @@ function format_class_members ($ns, $cl, &$dups) {
 			$rv.= format_doxydoc($f);
 		}
 	}
+	# print cast - if any
+	if (isset ($cl['cast'])) {
+		usort ($cl['cast'], 'name_sort_cb');
+		$rv.= ' <tr><th colspan="3">Cast</th></tr>'.NL;
+		foreach ($cl['cast'] as $f) {
+			$rv.= ' <tr><td class="def">';
+			$rv.= typelink (varname ($f['ret']), true, 'em');
+			# function declaration and arguments
+			$rv.= '</td><td class="decl">';
+			$rv.= '<span class="functionname"><abbr title="'.htmlentities($f['bind']['decl']).'">'.stripclass ($ns, $f['name']).'</abbr></span>';
+			$rv.= format_args ($f['args']);
+			$rv.= '</td><td class="fill"></td></tr>'.NL;
+			# doxygen documentation (may be empty)
+			$rv.= format_doxydoc($f);
+		}
+	}
+
 	# print data members - if any
 	if (isset ($cl['data'])) {
 		usort ($cl['data'], 'name_sort_cb');
@@ -781,6 +810,12 @@ Operations are performed on objects. One gets a reference to an object and then
 e.g <code>obj = Session:route_by_name("Audio")   obj:set_name("Guitar")</code>.
 </p>
 <p>
+Lua automatically follows C++ class inheritance. e.g one can directly call all SessionObject and Route methods on Track object. However lua does not automatically promote objects. A Route object which just happens to be a Track needs to be explicily cast to a Track. Methods for casts are provided with each class. Note that the cast may fail and return a <em>nil</em> reference.
+</p>
+<p>
+Likewise multiple inheritance is a <a href="http://www.lua.org/pil/16.3.html">non-trivial issue</a> in lua. To avoid performance penalties involved with lookups, explicit casts are required in this case. One example is <?=typelink('ARDOUR:SessionObject')?> which is-a StatefulDestructible which inhertis from both Stateful and Destructible.
+</p>
+<p>
 Object lifetimes are managed by the Session. Most Objects cannot be directly created, but one asks the Session to create or destroy them. This is mainly due to realtime constrains:
 you cannot simply remove a track that is currently processing audio. There are various <em>factory</em> methods for object creation or removal.
 </p>