update luadoc tools

diff --git a/tools/doxy2json/ardourdoc.sh b/tools/doxy2json/ardourdoc.sh
index 870c1e53c3c90b9feb8eeb2e798489d70bc40677..b9e7db8ff092b842ab98d46f4d881e042036cb7f 100755 (executable)
--- 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 e541f0cf98c96874a6a859ec7500163011aeb7f3..530a4d8c48e856259b868f12701f86f2c5e44fc0 100755 (executable)
--- 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>