diff --git a/gtk2_ardour/arluadoc b/gtk2_ardour/arluadoc
index 7ee75daff2..6509e8b1ef 100755
--- a/gtk2_ardour/arluadoc
+++ b/gtk2_ardour/arluadoc
@@ -11,5 +11,4 @@ $TOP/build/gtk2_ardour/luadoc "$@" \
| sed 's/, std::allocator<[^>]*<[^>]*>[ ]*>//g;' \
| sed 's/, std::allocator<[^>]*>//g;' \
| sed 's/ "/"/g;' \
- | sed 's/ const&//g;' \
- | sed 's/ const//g;'
+ | gzip -9
diff --git a/tools/doxy2json/ardourdoc.sh b/tools/doxy2json/ardourdoc.sh
index 548d403e61..8d69a64e28 100755
--- a/tools/doxy2json/ardourdoc.sh
+++ b/tools/doxy2json/ardourdoc.sh
@@ -49,7 +49,7 @@ foreach (json_decode (\$json, true) as \$a) {
foreach (\$api as \$k => \$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
-ls -l doc/ardourapi.json
+ls -l doc/ardourapi.json.gz
diff --git a/tools/fmt-luadoc.php b/tools/fmt-luadoc.php
index 80b5969894..683216fe0d 100755
--- a/tools/fmt-luadoc.php
+++ b/tools/fmt-luadoc.php
@@ -2,20 +2,31 @@
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
#
################################################################################
################################################################################
-$json = file_get_contents (dirname (__FILE__).'/../doc/luadoc.json');
+$json = gzdecode (file_get_contents (dirname (__FILE__).'/../doc/luadoc.json.gz'));
$doc = array ();
foreach (json_decode ($json, true) as $b) {
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;
}
@@ -56,13 +67,14 @@ function my_die ($msg) {
# return preg_replace ('/boost::shared_ptr<([^>]*)[ ]*>/', '$1', $ctype);
#}
-function arg2lua ($argtype) {
+function arg2lua ($argtype, $flags = 0) {
global $classes;
global $consts;
# LuaBridge abstracts C++ references
- $flags = preg_match ('/&$/', $argtype);
+ $flags |= preg_match ('/&$/', $argtype);
$arg = preg_replace ('/&$/', '', $argtype);
+ $arg = preg_replace ('/ $/', '', $arg);
# 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*');
@@ -72,7 +84,7 @@ function arg2lua ($argtype) {
# check Class declarations first
foreach (array_merge ($classes, $consts) as $b) {
- if ($b['decl'] == $arg) {
+ if ($b['ldec'] == $arg) {
return array ($b['lua'] => $flags);
}
}
@@ -80,11 +92,15 @@ function arg2lua ($argtype) {
# strip class pointers -- TODO Check C'tor for given class
$arg = preg_replace ('/[&*]*$/', '', $argtype);
foreach (array_merge ($classes, $consts) as $b) {
- if ($b['decl'] == $arg) {
+ if ($b['ldec'] == $arg) {
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) {
@@ -126,6 +142,41 @@ function decl2args ($decl) {
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
@@ -134,7 +185,7 @@ foreach ($doc as $b) {
$classes[] = $b;
$classlist[$b['lua']] = $b;
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']) {
case "Constant/Enum":
case "Constant/Enum Member":
- if (strpos ($b['decl'], '::') === false) {
+ if (strpos ($b['ldec'], '::') === false) {
# 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;
# arg2lua lookup
$b['lua'] = $ns;
@@ -178,30 +229,32 @@ foreach ($doc as $b) {
checkclass ($b);
$classlist[luafn2class ($b['lua'])]['ctor'][] = array (
'name' => luafn2class ($b['lua']),
- 'args' => decl2args ($b['decl']),
+ 'args' => decl2args ($b['ldec']),
+ 'cand' => canonical_ctor ($b)
);
break;
case "Data Member":
checkclass ($b);
$classlist[luafn2class ($b['lua'])]['data'][] = array (
'name' => $b['lua'],
- 'ret' => arg2lua (datatype ($b['decl']))
+ 'ret' => arg2lua (datatype ($b['ldec']))
);
break;
case "C Function":
# we required C functions to be in a class namespace
case "Ext C Function":
checkclass ($b);
- $args = array (array ('--custom--' => 0));
+ $args = array (array ('--lua--' => 0));
$ret = array ('...' => 0);
$ns = luafn2class ($b['lua']);
$cls = $classlist[$ns];
## std::Vector std::List types
- if (preg_match ('/.*<([^>]*)[ ]*>/', $cls['decl'], $templ)) {
+ if (preg_match ('/.*<([^>]*)[ ]*>/', $cls['ldec'], $templ)) {
// XXX -> move to C-source
switch (stripclass($ns, $b['lua'])) {
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);
break;
case 'iter':
@@ -216,7 +269,7 @@ foreach ($doc as $b) {
break;
}
} else if (strpos ($cls['type'], ' Array') !== false) {
- $templ = preg_replace ('/[&*]*$/', '', $cls['decl']);
+ $templ = preg_replace ('/[&*]*$/', '', $cls['ldec']);
switch (stripclass($ns, $b['lua'])) {
case 'array':
$args = array ();
@@ -240,7 +293,8 @@ foreach ($doc as $b) {
'args' => $args,
'ret' => $ret,
'ref' => true,
- 'ext' => true
+ 'ext' => true,
+ 'cand' => canonical_decl ($b)
);
break;
case "Free Function":
@@ -248,9 +302,10 @@ foreach ($doc as $b) {
$funclist[luafn2class ($b['lua'])][] = array (
'bind' => $b,
'name' => $b['lua'],
- 'args' => decl2args ($b['decl']),
+ 'args' => decl2args ($b['ldec']),
'ret' => arg2lua ($b['ret']),
- 'ref' => (strpos ($b['type'], "RefReturn") !== false)
+ 'ref' => (strpos ($b['type'], "RefReturn") !== false),
+ 'cand' => canonical_decl ($b)
);
break;
case "Member Function":
@@ -265,9 +320,10 @@ foreach ($doc as $b) {
$classlist[luafn2class ($b['lua'])]['func'][] = array (
'bind' => $b,
'name' => $b['lua'],
- 'args' => decl2args ($b['decl']),
+ 'args' => decl2args ($b['ldec']),
'ret' => arg2lua ($b['ret']),
- 'ref' => (strpos ($b['type'], "RefReturn") !== false)
+ 'ref' => (strpos ($b['type'], "RefReturn") !== false),
+ 'cand' => canonical_decl ($b)
);
break;
case "Constant/Enum":
@@ -332,10 +388,35 @@ ksort ($classlist);
# from here on, only $classlist and $constlist arrays are relevant.
-# TODO: read function documentation from doxygen
-# and/or reference source-code lines e.g from CSV list:
-# ctags -o /tmp/tags.csv --fields=+afiKkmnsSzt libs/ardour/ardour/session.h
+# read function documentation from doxygen
+$json = gzdecode (file_get_contents (dirname (__FILE__).'/../doc/ardourapi.json.gz'));
+$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
@@ -400,9 +481,13 @@ function format_args ($args) {
foreach ($args as $a) {
if (!$first) { $rv .= ', '; }; $first = false;
$flags = $a[varname ($a)];
- if ($flags & 1) {
+ if ($flags & 2) {
+ $rv .= 'LuaTable {'.typelink (varname ($a), true, 'em').'}';
+ }
+ elseif ($flags & 1) {
$rv .= typelink (varname ($a), true, 'em', '', '&');
- } else {
+ }
+ else {
$rv .= typelink (varname ($a), true, 'em');
}
}
@@ -410,6 +495,31 @@ function format_args ($args) {
return $rv;
}
+function format_doxyclass ($cl) {
+ $rv = '';
+ if (isset ($cl['decl'])) {
+ $doc = doxydoc ($cl['decl']);
+ if (!empty ($doc)) {
+ $rv.= ''.$doc.'
'.NL;
+ }
+ }
+ return $rv;
+}
+
+function format_doxydoc ($f) {
+ $rv = '';
+ if (isset ($f['cand'])) {
+ $doc = doxydoc ($f['cand']);
+ if (!empty ($doc)) {
+ $rv.= ' | '.$doc;
+ $rv.= ' |
'.NL;
+ } else if (0) { # debug
+ $rv.= ' | '.htmlentities($f['cand']).' ';
+ $rv.= ' |
'.NL;
+ }
+ }
+ return $rv;
+}
function format_class_members ($ns, $cl, &$dups) {
$rv = '';
if (isset ($cl['ctor'])) {
@@ -420,6 +530,7 @@ function format_class_members ($ns, $cl, &$dups) {
$rv.= ''.ctorname ($f['name']).'';
$rv.= format_args ($f['args']);
$rv.= ' | '.NL;
+ $rv.= format_doxydoc($f);
}
}
$nondups = array ();
@@ -442,7 +553,7 @@ function format_class_members ($ns, $cl, &$dups) {
# functions with reference args return args
$rv.= 'LuaTable(...)';
} elseif ($f['ref']) {
- $rv.= 'LuaTable('.typelink (varname ($f['ret'], false, 'em')).', ...)';
+ $rv.= 'LuaTable('.typelink (varname ($f['ret']), true, 'em').', ...)';
} else {
$rv.= typelink (varname ($f['ret']), true, 'em');
}
@@ -450,6 +561,7 @@ function format_class_members ($ns, $cl, &$dups) {
$rv.= ''.stripclass ($ns, $f['name']).'';
$rv.= format_args ($f['args']);
$rv.= ' | '.NL;
+ $rv.= format_doxydoc($f);
}
}
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;}
ul.classindex { columns: 2; -webkit-columns: 2; -moz-columns: 2; }
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 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.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 span.em { font-style: italic;}
span.functionname abbr { text-decoration:none; cursor:default;}
@@ -571,13 +696,15 @@ foreach ($classlist as $ns => $cl) {
$inherited = array ();
$isa = traverse_parent ($ns, $inherited);
if (!empty ($isa)) {
- echo ' is-a: '.$isa.'
'.NL;
+ echo ' is-a: '.$isa.'
'.NL;
}
echo ''.NL;
+ echo format_doxyclass ($cl);
+
# member documentation
if (empty ($tbl)) {
- echo 'This class object is only used indirectly as return-value and function-parameter.
'.NL;
+ echo 'This class object is only used indirectly as return-value and function-parameter. It provides no methods by itself.
'.NL;
} else {
echo ''.NL;
echo $tbl;
@@ -613,6 +740,7 @@ foreach ($classlist as $ns => $cl) {
}
echo ''.NL;
+fwrite (STDERR, "Found $dox_found annotations. missing: $dox_miss\n");
?>