ardour/livetrax
13
0
Fork 0
Code

add doxygen comments to lua-binding doc, compress json.

Browse Source
This commit is contained in:
Robin Gareus 2016-03-24 22:02:38 +01:00
parent 6188315791
commit e0e98d45d4
3 changed files with 161 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
gtk2_ardour/arluadoc
View File

@ -11,5 +11,4 @@ $TOP/build/gtk2_ardour/luadoc "$@" \
| sed 's/, std::allocator<[^>]*<[^>]*>[ ]*>//g;' \ | sed 's/, std::allocator<[^>]*<[^>]*>[ ]*>//g;' \
| sed 's/, std::allocator<[^>]*>//g;' \ | sed 's/, std::allocator<[^>]*>//g;' \
| sed 's/ "/"/g;' \ | sed 's/ "/"/g;' \
| sed 's/ const&//g;' \ | gzip -9
| sed 's/ const//g;'

4
tools/doxy2json/ardourdoc.sh
View File

@ -49,7 +49,7 @@ foreach (json_decode (\$json, true) as \$a) {
foreach (\$api as \$k => \$a) { foreach (\$api as \$k => \$a) {
\$jout[] = \$a; \$jout[] = \$a;
} }
file_put_contents('doc/ardourapi.json', json_encode (\$jout, JSON_PRETTY_PRINT)); file_put_contents('doc/ardourapi.json.gz', gzencode (json_encode (\$jout, JSON_PRETTY_PRINT)));
EOF EOF
ls -l doc/ardourapi.json ls -l doc/ardourapi.json.gz

188
tools/fmt-luadoc.php
View File

@ -2,20 +2,31 @@
<?php <?php
## USAGE ## USAGE
# #
## generate doc/luadoc.json.gz (lua binding doc)
# ./waf configure --luadoc .... # ./waf configure --luadoc ....
# ./waf # ./waf
# ./gtk2_ardour/arluadoc > doc/luadoc.json # ./gtk2_ardour/arluadoc > doc/luadoc.json.gz
# #
## generate doc/ardourapi.json.gz (ardour header doxygen doc)
# cd ../../tools/doxy2json
# ./ardourdoc.sh
# cd -
#
## format HTML (using this scripterl)
# php tools/fmt-luadoc.php > /tmp/luadoc.html # php tools/fmt-luadoc.php > /tmp/luadoc.html
# #
################################################################################ ################################################################################
################################################################################ ################################################################################
$json = file_get_contents (dirname (__FILE__).'/../doc/luadoc.json'); $json = gzdecode (file_get_contents (dirname (__FILE__).'/../doc/luadoc.json.gz'));
$doc = array (); $doc = array ();
foreach (json_decode ($json, true) as $b) { foreach (json_decode ($json, true) as $b) {
if (!isset ($b['type'])) { continue; } if (!isset ($b['type'])) { continue; }
$b ['ldec'] = preg_replace ('/ const/', '', preg_replace ('/ const&/', '', $b['decl']));
if (isset ($b['ret'])) {
$b['ret'] = preg_replace ('/ const/', '', preg_replace ('/ const&/', '', $b['ret']));
}
$doc[] = $b; $doc[] = $b;
} }
@ -56,13 +67,14 @@ function my_die ($msg) {
# return preg_replace ('/boost::shared_ptr<([^>]*)[ ]*>/', '$1', $ctype); # return preg_replace ('/boost::shared_ptr<([^>]*)[ ]*>/', '$1', $ctype);
#} #}
function arg2lua ($argtype) { function arg2lua ($argtype, $flags = 0) {
global $classes; global $classes;
global $consts; global $consts;
# LuaBridge abstracts C++ references # LuaBridge abstracts C++ references
$flags = preg_match ('/&$/', $argtype); $flags |= preg_match ('/&$/', $argtype);
$arg = preg_replace ('/&$/', '', $argtype); $arg = preg_replace ('/&$/', '', $argtype);
$arg = preg_replace ('/ $/', '', $arg);
# filter out basic types # filter out basic types
$builtin = array ('float', 'double', 'bool', 'std::string', 'int', 'long', 'unsigned long', 'unsigned int', 'unsigned char', 'char', 'void', 'char*', 'unsigned char*', 'void*'); $builtin = array ('float', 'double', 'bool', 'std::string', 'int', 'long', 'unsigned long', 'unsigned int', 'unsigned char', 'char', 'void', 'char*', 'unsigned char*', 'void*');
@ -72,7 +84,7 @@ function arg2lua ($argtype) {
# check Class declarations first # check Class declarations first
foreach (array_merge ($classes, $consts) as $b) { foreach (array_merge ($classes, $consts) as $b) {
if ($b['decl'] == $arg) { if ($b['ldec'] == $arg) {
return array ($b['lua'] => $flags); return array ($b['lua'] => $flags);
} }
} }
@ -80,11 +92,15 @@ function arg2lua ($argtype) {
# strip class pointers -- TODO Check C'tor for given class # strip class pointers -- TODO Check C'tor for given class
$arg = preg_replace ('/[&*]*$/', '', $argtype); $arg = preg_replace ('/[&*]*$/', '', $argtype);
foreach (array_merge ($classes, $consts) as $b) { foreach (array_merge ($classes, $consts) as $b) {
if ($b['decl'] == $arg) { if ($b['ldec'] == $arg) {
return array ($b['lua'] => $flags); return array ($b['lua'] => $flags);
} }
} }
return array ('--MISSING (' . $argtype . ')--' => ($flags | 4)); if ($flags & 2) {
return array ($argtype => ($flags | 4));
} else {
return array ('--MISSING (' . $argtype . ')--' => ($flags | 4));
}
} }
function stripclass ($classname, $name) { function stripclass ($classname, $name) {
@ -126,6 +142,41 @@ function decl2args ($decl) {
return $rv; return $rv;
} }
function canonical_ctor ($b) {
$rv = '';
if (preg_match('/[^(]*\(([^)*]*)\*\)(\(.*\))/', $b['decl'], $matches)) {
$lc = luafn2class ($b['lua']);
$cn = str_replace (':', '::', $lc);
$fn = substr ($lc, 1 + strrpos ($lc, ':'));
$rv = $cn . '::'. $fn . $matches[2];
}
return $rv;
}
function canonical_decl ($b) {
$rv = '';
# match clang's declatation format
if (preg_match('/[^(]*\(([^)*]*)\*\)\((.*)\)/', $b['decl'], $matches)) {
$fn = substr ($b['lua'], 1 + strrpos ($b['lua'], ':'));
$rv = $matches[1] . $fn . '(';
$arglist = preg_split ('/, */', $matches[2]);
$first = true;
foreach ($arglist as $a) {
if (!$first) { $rv .= ', '; }; $first = false;
if (empty ($a)) { continue; }
$a = preg_replace ('/([^>]) >/', '$1>', $a);
$a = preg_replace ('/^.*::/', '', $a);
$a = preg_replace ('/([^ ])&/', '$1 &', $a);
$a = str_replace ('vector', 'std::vector', $a);
$a = str_replace ('string const', 'const string', $a);
$a = str_replace ('string', 'std::string', $a);
$rv .= $a;
}
$rv .= ')';
}
return $rv;
}
################################################################################ ################################################################################
# step 1: build class indices # step 1: build class indices
@ -134,7 +185,7 @@ foreach ($doc as $b) {
$classes[] = $b; $classes[] = $b;
$classlist[$b['lua']] = $b; $classlist[$b['lua']] = $b;
if (strpos ($b['type'], 'Pointer Class') === false) { if (strpos ($b['type'], 'Pointer Class') === false) {
$classdecl[$b['decl']] = $b; $classdecl[$b['ldec']] = $b;
} }
} }
} }
@ -155,11 +206,11 @@ foreach ($doc as $b) {
switch ($b['type']) { switch ($b['type']) {
case "Constant/Enum": case "Constant/Enum":
case "Constant/Enum Member": case "Constant/Enum Member":
if (strpos ($b['decl'], '::') === false) { if (strpos ($b['ldec'], '::') === false) {
# for extern c enums, use the Lua Namespace # for extern c enums, use the Lua Namespace
$b['decl'] = str_replace (':', '::', luafn2class ($b['lua'])); $b['ldec'] = str_replace (':', '::', luafn2class ($b['lua']));
} }
$ns = str_replace ('::', ':', $b['decl']); $ns = str_replace ('::', ':', $b['ldec']);
$constlist[$ns][] = $b; $constlist[$ns][] = $b;
# arg2lua lookup # arg2lua lookup
$b['lua'] = $ns; $b['lua'] = $ns;
@ -178,30 +229,32 @@ foreach ($doc as $b) {
checkclass ($b); checkclass ($b);
$classlist[luafn2class ($b['lua'])]['ctor'][] = array ( $classlist[luafn2class ($b['lua'])]['ctor'][] = array (
'name' => luafn2class ($b['lua']), 'name' => luafn2class ($b['lua']),
'args' => decl2args ($b['decl']), 'args' => decl2args ($b['ldec']),
'cand' => canonical_ctor ($b)
); );
break; break;
case "Data Member": case "Data Member":
checkclass ($b); checkclass ($b);
$classlist[luafn2class ($b['lua'])]['data'][] = array ( $classlist[luafn2class ($b['lua'])]['data'][] = array (
'name' => $b['lua'], 'name' => $b['lua'],
'ret' => arg2lua (datatype ($b['decl'])) 'ret' => arg2lua (datatype ($b['ldec']))
); );
break; break;
case "C Function": case "C Function":
# we required C functions to be in a class namespace # we required C functions to be in a class namespace
case "Ext C Function": case "Ext C Function":
checkclass ($b); checkclass ($b);
$args = array (array ('--custom--' => 0)); $args = array (array ('--lua--' => 0));
$ret = array ('...' => 0); $ret = array ('...' => 0);
$ns = luafn2class ($b['lua']); $ns = luafn2class ($b['lua']);
$cls = $classlist[$ns]; $cls = $classlist[$ns];
## std::Vector std::List types ## std::Vector std::List types
if (preg_match ('/.*<([^>]*)[ ]*>/', $cls['decl'], $templ)) { if (preg_match ('/.*<([^>]*)[ ]*>/', $cls['ldec'], $templ)) {
// XXX -> move to C-source // XXX -> move to C-source
switch (stripclass($ns, $b['lua'])) { switch (stripclass($ns, $b['lua'])) {
case 'add': case 'add':
$args = array (array ('LuaTable {'.$templ[1].'}' => 0)); #$args = array (array ('LuaTable {'.$templ[1].'}' => 0));
$args = array (arg2lua ($templ[1], 2));
$ret = array ('LuaTable' => 0); $ret = array ('LuaTable' => 0);
break; break;
case 'iter': case 'iter':
@ -216,7 +269,7 @@ foreach ($doc as $b) {
break; break;
} }
} else if (strpos ($cls['type'], ' Array') !== false) { } else if (strpos ($cls['type'], ' Array') !== false) {
$templ = preg_replace ('/[&*]*$/', '', $cls['decl']); $templ = preg_replace ('/[&*]*$/', '', $cls['ldec']);
switch (stripclass($ns, $b['lua'])) { switch (stripclass($ns, $b['lua'])) {
case 'array': case 'array':
$args = array (); $args = array ();
@ -240,7 +293,8 @@ foreach ($doc as $b) {
'args' => $args, 'args' => $args,
'ret' => $ret, 'ret' => $ret,
'ref' => true, 'ref' => true,
'ext' => true 'ext' => true,
'cand' => canonical_decl ($b)
); );
break; break;
case "Free Function": case "Free Function":
@ -248,9 +302,10 @@ foreach ($doc as $b) {
$funclist[luafn2class ($b['lua'])][] = array ( $funclist[luafn2class ($b['lua'])][] = array (
'bind' => $b, 'bind' => $b,
'name' => $b['lua'], 'name' => $b['lua'],
'args' => decl2args ($b['decl']), 'args' => decl2args ($b['ldec']),
'ret' => arg2lua ($b['ret']), 'ret' => arg2lua ($b['ret']),
'ref' => (strpos ($b['type'], "RefReturn") !== false) 'ref' => (strpos ($b['type'], "RefReturn") !== false),
'cand' => canonical_decl ($b)
); );
break; break;
case "Member Function": case "Member Function":
@ -265,9 +320,10 @@ foreach ($doc as $b) {
$classlist[luafn2class ($b['lua'])]['func'][] = array ( $classlist[luafn2class ($b['lua'])]['func'][] = array (
'bind' => $b, 'bind' => $b,
'name' => $b['lua'], 'name' => $b['lua'],
'args' => decl2args ($b['decl']), 'args' => decl2args ($b['ldec']),
'ret' => arg2lua ($b['ret']), 'ret' => arg2lua ($b['ret']),
'ref' => (strpos ($b['type'], "RefReturn") !== false) 'ref' => (strpos ($b['type'], "RefReturn") !== false),
'cand' => canonical_decl ($b)
); );
break; break;
case "Constant/Enum": case "Constant/Enum":
@ -332,10 +388,35 @@ ksort ($classlist);
# from here on, only $classlist and $constlist arrays are relevant. # from here on, only $classlist and $constlist arrays are relevant.
# TODO: read function documentation from doxygen # read function documentation from doxygen
# and/or reference source-code lines e.g from CSV list: $json = gzdecode (file_get_contents (dirname (__FILE__).'/../doc/ardourapi.json.gz'));
# ctags -o /tmp/tags.csv --fields=+afiKkmnsSzt libs/ardour/ardour/session.h $api = array ();
foreach (json_decode ($json, true) as $a) {
if (!isset ($a['decl'])) { continue; }
if (empty ($a['decl'])) { continue; }
$canon = str_replace (' *', '*', $a['decl']);
$api[$canon] = $a;
}
$dox_found = 0;
$dox_miss = 0;
function doxydoc ($canonical_declaration) {
global $api;
global $dox_found;
global $dox_miss;
if (isset ($api[$canonical_declaration])) {
$dox_found++;
return $api[$canonical_declaration]['doc'];
}
elseif (isset ($api['ARDOUR::'.$canonical_declaration])) {
$dox_found++;
return $api['ARDOUR::'.$canonical_declaration]['doc'];
}
else {
$dox_miss++;
return '';
}
}
################################################################################ ################################################################################
# OUTPUT # OUTPUT
@ -400,9 +481,13 @@ function format_args ($args) {
foreach ($args as $a) { foreach ($args as $a) {
if (!$first) { $rv .= ', '; }; $first = false; if (!$first) { $rv .= ', '; }; $first = false;
$flags = $a[varname ($a)]; $flags = $a[varname ($a)];
if ($flags & 1) { if ($flags & 2) {
$rv .= '<em>LuaTable</em> {'.typelink (varname ($a), true, 'em').'}';
}
elseif ($flags & 1) {
$rv .= typelink (varname ($a), true, 'em', '', '&amp;'); $rv .= typelink (varname ($a), true, 'em', '', '&amp;');
} else { }
else {
$rv .= typelink (varname ($a), true, 'em'); $rv .= typelink (varname ($a), true, 'em');
} }
} }
@ -410,6 +495,31 @@ function format_args ($args) {
return $rv; return $rv;
} }
function format_doxyclass ($cl) {
$rv = '';
if (isset ($cl['decl'])) {
$doc = doxydoc ($cl['decl']);
if (!empty ($doc)) {
$rv.= '<div class="classdox">'.$doc.'</div>'.NL;
}
}
return $rv;
}
function format_doxydoc ($f) {
$rv = '';
if (isset ($f['cand'])) {
$doc = doxydoc ($f['cand']);
if (!empty ($doc)) {
$rv.= '<tr><td></td><td class="doc" colspan="2"><div class="dox">'.$doc;
$rv.= '</div></td></tr>'.NL;
} else if (0) { # debug
$rv.= '<tr><td></td><td class="doc" colspan="2"><p>'.htmlentities($f['cand']).'</p>';
$rv.= '</td></tr>'.NL;
}
}
return $rv;
}
function format_class_members ($ns, $cl, &$dups) { function format_class_members ($ns, $cl, &$dups) {
$rv = ''; $rv = '';
if (isset ($cl['ctor'])) { if (isset ($cl['ctor'])) {
@ -420,6 +530,7 @@ function format_class_members ($ns, $cl, &$dups) {
$rv.= '<span class="functionname">'.ctorname ($f['name']).'</span>'; $rv.= '<span class="functionname">'.ctorname ($f['name']).'</span>';
$rv.= format_args ($f['args']); $rv.= format_args ($f['args']);
$rv.= '</td><td class="fill"></td></tr>'.NL; $rv.= '</td><td class="fill"></td></tr>'.NL;
$rv.= format_doxydoc($f);
} }
} }
$nondups = array (); $nondups = array ();
@ -442,7 +553,7 @@ function format_class_members ($ns, $cl, &$dups) {
# functions with reference args return args # functions with reference args return args
$rv.= '<em>LuaTable</em>(...)'; $rv.= '<em>LuaTable</em>(...)';
} elseif ($f['ref']) { } elseif ($f['ref']) {
$rv.= '<em>LuaTable</em>('.typelink (varname ($f['ret'], false, 'em')).', ...)'; $rv.= '<em>LuaTable</em>('.typelink (varname ($f['ret']), true, 'em').', ...)';
} else { } else {
$rv.= typelink (varname ($f['ret']), true, 'em'); $rv.= typelink (varname ($f['ret']), true, 'em');
} }
@ -450,6 +561,7 @@ function format_class_members ($ns, $cl, &$dups) {
$rv.= '<span class="functionname"><abbr title="'.htmlentities($f['bind']['decl']).'">'.stripclass ($ns, $f['name']).'</abbr></span>'; $rv.= '<span class="functionname"><abbr title="'.htmlentities($f['bind']['decl']).'">'.stripclass ($ns, $f['name']).'</abbr></span>';
$rv.= format_args ($f['args']); $rv.= format_args ($f['args']);
$rv.= '</td><td class="fill"></td></tr>'.NL; $rv.= '</td><td class="fill"></td></tr>'.NL;
$rv.= format_doxydoc($f);
} }
} }
if (isset ($cl['data'])) { if (isset ($cl['data'])) {
@ -487,10 +599,23 @@ h2.opaque { background-color: #6666aa; }
p.cdecl { text-align: right; float:right; font-size:90%; margin:0; padding: 0 0 0 1em;} p.cdecl { text-align: right; float:right; font-size:90%; margin:0; padding: 0 0 0 1em;}
ul.classindex { columns: 2; -webkit-columns: 2; -moz-columns: 2; } ul.classindex { columns: 2; -webkit-columns: 2; -moz-columns: 2; }
div.clear { clear:both; } div.clear { clear:both; }
p.classinfo { margin: .25em 0;}
div.classdox { padding: .1em 1em;}
div.classdox p { margin: .5em 0 .5em .6em;}
div.classdox p { margin: .5em 0 .5em .6em;}
div.classdox { padding: .1em 1em;}
div.classdox p { margin: .5em 0 .5em .6em;}
table.classmembers { width: 100%; } table.classmembers { width: 100%; }
table.classmembers th { text-align:left; border-bottom:1px solid black; padding-top:1em; } table.classmembers th { text-align:left; border-bottom:1px solid black; padding-top:1em; }
table.classmembers td.def { text-align:right; padding-right:.5em; white-space: nowrap;} table.classmembers td.def { text-align:right; padding-right:.5em; white-space: nowrap;}
table.classmembers td.decl { text-align:left; padding-left:.5em; white-space: nowrap; } table.classmembers td.decl { text-align:left; padding-left:.5em; white-space: nowrap; }
table.classmembers td.doc { text-align:left; padding-left:.6em; line-height: 1.2em; font-size:80%;}
table.classmembers td.doc div.dox {background-color:#ddd; padding: .1em 1em;}
table.classmembers td.doc p { margin: .5em 0; }
table.classmembers td.doc p.para-brief { font-size:120%; }
table.classmembers td.doc p.para-returns { font-size:120%; }
table.classmembers td.doc dl { font-size:120%; line-height: 1.3em; }
table.classmembers td.doc dt { font-style: italic; }
table.classmembers td.fill { width: 99%;} table.classmembers td.fill { width: 99%;}
table.classmembers span.em { font-style: italic;} table.classmembers span.em { font-style: italic;}
span.functionname abbr { text-decoration:none; cursor:default;} span.functionname abbr { text-decoration:none; cursor:default;}
@ -571,13 +696,15 @@ foreach ($classlist as $ns => $cl) {
$inherited = array (); $inherited = array ();
$isa = traverse_parent ($ns, $inherited); $isa = traverse_parent ($ns, $inherited);
if (!empty ($isa)) { if (!empty ($isa)) {
echo ' <p>is-a: '.$isa.'</p>'.NL; echo ' <p class="classinfo">is-a: '.$isa.'</p>'.NL;
} }
echo '<div class="clear"></div>'.NL; echo '<div class="clear"></div>'.NL;
echo format_doxyclass ($cl);
# member documentation # member documentation
if (empty ($tbl)) { if (empty ($tbl)) {
echo '<p>This class object is only used indirectly as return-value and function-parameter.</p>'.NL; echo '<p class="classinfo">This class object is only used indirectly as return-value and function-parameter. It provides no methods by itself.</p>'.NL;
} else { } else {
echo '<table class="classmembers">'.NL; echo '<table class="classmembers">'.NL;
echo $tbl; echo $tbl;
@ -613,6 +740,7 @@ foreach ($classlist as $ns => $cl) {
} }
echo '</ul>'.NL; echo '</ul>'.NL;
fwrite (STDERR, "Found $dox_found annotations. missing: $dox_miss\n");
?> ?>
</div> </div>
</body> </body>