X-Git-Url: https://main.carlh.net/gitweb/?a=blobdiff_plain;f=tools%2Ffmt-luadoc.php;h=b3d2c0eb714e512161282f575ba80829f2930606;hb=b9ba91ac1d20fb57eb19a6639080ae45244436b8;hp=712c8b0887196d1dbfdf661144154fabfe20224e;hpb=22b1a0b6aec9651549e75469c4de43ea33c62f3a;p=ardour.git diff --git a/tools/fmt-luadoc.php b/tools/fmt-luadoc.php index 712c8b0887..b3d2c0eb71 100755 --- a/tools/fmt-luadoc.php +++ b/tools/fmt-luadoc.php @@ -16,6 +16,13 @@ # php tools/fmt-luadoc.php > /tmp/luadoc.html # +$options = getopt("m"); +if (isset ($options['m'])) { + $HTMLOUTPUT = false; ## set to false to output ardour-manual +} else { + $HTMLOUTPUT = true; ## set to false to output ardour-manual +} + ################################################################################ ################################################################################ @@ -27,6 +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'])); @@ -118,7 +128,7 @@ function stripclass ($classname, $name) { function datatype ($decl) { # TODO handle spaces in type. Works because # we don't yet have templated types (with_space ) - return substr ($decl, 0, strpos ($decl, ' ')); + return substr ($decl, 0, strrpos ($decl, ' ')); } function luafn2class ($lua) { @@ -335,6 +345,17 @@ foreach ($doc as $b) { 'cand' => canonical_decl ($b) ); break; + case "Free C Function": + $funclist[luafn2class ($b['lua'])][] = array ( + 'bind' => $b, + 'name' => $b['lua'], + 'args' => $args, + 'ret' => $ret, + 'ref' => false, + 'ext' => true, + 'cand' => str_replace (':', '::', $b['lua']).'(lua_State*)' + ); + break; case "Free Function": case "Free Function RefReturn": $funclist[luafn2class ($b['lua'])][] = array ( @@ -352,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 ( @@ -364,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 @@ -383,14 +414,17 @@ foreach ($doc as $b) { foreach ($classlist as $ns => $cl) { if (strpos ($cl['type'], ' Array') !== false) { $classlist[$ns]['arr'] = true; + $classlist[$ns]['cdecl'] = $cl['decl']; continue; } foreach ($classes as $c) { if ($c['lua'] == $ns) { if (strpos ($c['type'], 'Pointer Class') !== false) { $classlist[$ns]['ptr'] = true; - $classlist[$ns]['decl'] = 'boost::shared_ptr< '.$c['decl']. ' >, boost::weak_ptr< '.$c['decl']. ' >'; + $classlist[$ns]['cdecl'] = 'boost::shared_ptr< '.$c['decl']. ' >, boost::weak_ptr< '.$c['decl']. ' >'; break; + } else { + $classlist[$ns]['cdecl'] = $c['decl']; } } } @@ -450,10 +484,19 @@ function doxydoc ($canonical_declaration) { if (isset ($api[$canonical_declaration])) { $dox_found++; return $api[$canonical_declaration]['doc']; - } else { - $dox_miss++; - return ''; } + // remove template namespace e.g. + // "ARDOUR::Track::bounceable(boost::shared_ptr" + // "ARDOUR::Track::bounceable(boost::shared_ptr" + $cn = preg_replace ('/<[^>]*::([^>]*)>/', '<$1>', $canonical_declaration); + if (isset ($api[$cn])) { + $dox_found++; + return $api[$cn]['doc']; + } + #fwrite (STDERR, $canonical_declaration."\n"); # XXX DEBUG + + $dox_miss++; + return ''; } ################################################################################ @@ -625,6 +668,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.= ' Cast'.NL; + foreach ($cl['cast'] as $f) { + $rv.= ' '; + $rv.= typelink (varname ($f['ret']), true, 'em'); + # function declaration and arguments + $rv.= ''; + $rv.= ''.stripclass ($ns, $f['name']).''; + $rv.= format_args ($f['args']); + $rv.= ''.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'); @@ -642,6 +702,8 @@ function format_class_members ($ns, $cl, &$dups) { ################################################################################ # Start Output +if ($HTMLOUTPUT) { + ?> @@ -705,7 +767,26 @@ div.luafooter { text-align:center; font-size:80%; color: #888; margin: 2em

- + + + +--- +layout: default +style: luadoc +title: Class Reference +--- + +

+This documentation is far from complete may be inaccurate and subject to change. +

+ +
@@ -741,6 +822,12 @@ Operations are performed on objects. One gets a reference to an object and then e.g obj = Session:route_by_name("Audio") obj:set_name("Guitar").

+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 nil reference. +

+

+Likewise multiple inheritance is a non-trivial issue in lua. To avoid performance penalties involved with lookups, explicit casts are required in this case. One example is which is-a StatefulDestructible which inhertis from both Stateful and Destructible. +

+

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 factory methods for object creation or removal.

@@ -856,8 +943,8 @@ foreach ($classlist as $ns => $cl) { } # show original C++ declaration - if (isset ($cl['decl'])) { - echo '

C‡: '.htmlentities ($cl['decl']).'

'.NL; + if (isset ($cl['cdecl'])) { + echo '

C‡: '.htmlentities ($cl['cdecl']).'

'.NL; } # print class inheritance (direct parent *name* only) @@ -919,12 +1006,15 @@ echo ''.NL; # see how far there is still to go... fwrite (STDERR, "Found $dox_found annotations. missing: $dox_miss\n"); +echo ''.NL; ?>
Ardour  - 
+ - - - +if ($HTMLOUTPUT) { + echo ''.NL; + echo ''.NL; + echo ''.NL; +}