Overview
The top-level entry point are =typelink('ARDOUR:Session')?> and =typelink('ArdourUI:Editor')?>. @@ -693,7 +729,7 @@ If the C++ method also returns a value it is prefixed. Two parameters are return } -
diff --git a/doc/luadoc.json.gz b/doc/luadoc.json.gz
index 9d69fa89a8..fa7a8e70e4 100644
Binary files a/doc/luadoc.json.gz and b/doc/luadoc.json.gz differ
diff --git a/tools/fmt-luadoc.php b/tools/fmt-luadoc.php
index f35b829380..60d89728e3 100755
--- a/tools/fmt-luadoc.php
+++ b/tools/fmt-luadoc.php
@@ -21,8 +21,12 @@
$json = gzdecode (file_get_contents (dirname (__FILE__).'/../doc/luadoc.json.gz'));
$doc = array ();
+$ardourversion = '';
foreach (json_decode ($json, true) as $b) {
- if (!isset ($b['type'])) { continue; }
+ if (!isset ($b['type'])) {
+ if (isset ($b['version'])) { $ardourversion = $b['version']; }
+ 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']));
@@ -392,8 +396,10 @@ ksort ($classlist);
#### -- split here -- ####
# from here on, only $classlist and $constlist arrays are relevant.
+# we also pull in C++ header annotation from doxygen to $api
-# read function documentation from doxygen
+
+# read documentation from doxygen
$json = gzdecode (file_get_contents (dirname (__FILE__).'/../doc/ardourapi.json.gz'));
$api = array ();
foreach (json_decode ($json, true) as $a) {
@@ -403,8 +409,11 @@ foreach (json_decode ($json, true) as $a) {
$api[$canon] = $a;
}
+# keep track of found/missing doc
$dox_found = 0;
$dox_miss = 0;
+
+# retrive a value from $api
function doxydoc ($canonical_declaration) {
global $api;
global $dox_found;
@@ -412,12 +421,7 @@ function doxydoc ($canonical_declaration) {
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 {
+ } else {
$dox_miss++;
return '';
}
@@ -432,22 +436,22 @@ function doxydoc ($canonical_declaration) {
# Helper functions
define ('NL', "\n");
+# constructors, enums (constants) use a dot. (e.g. "LuaOSC.Address" -> "LuaOSC.Address" )
function ctorname ($name) {
return htmlentities (str_replace (':', '.', $name));
}
+# strip class prefix (e.g "Evoral:MidiEvent:channel" -> "channel")
function shortname ($name) {
return htmlentities (substr ($name, strrpos ($name, ':') + 1));
}
+# retrieve variable name from array["VARNAME"] => FLAGS
function varname ($a) {
return array_keys ($a)[0];
}
-function name_sort_cb ($a, $b) {
- return strcmp ($a['name'], $b['name']);
-}
-
+# recusively collect class parents (derived classes)
function traverse_parent ($ns, &$inherited) {
global $classlist;
$rv = '';
@@ -464,11 +468,11 @@ function traverse_parent ($ns, &$inherited) {
return $rv;
}
+# create a cross-reference to a type (class or enum)
+# *all* links are generated here, currently anchors on a single page.
function typelink ($a, $short = false, $argcls = '', $linkcls = '', $suffix = '') {
global $classlist;
global $constlist;
- # all cross-reference links are generated here.
- # currently anchors on a single page.
if (isset($classlist[$a]['free'])) {
return ''.($short ? shortname($a) : ctorname($a)).$suffix.'';
} else if (in_array ($a, array_keys ($classlist))) {
@@ -480,6 +484,7 @@ function typelink ($a, $short = false, $argcls = '', $linkcls = '', $suffix = ''
}
}
+# output format function arguments
function format_args ($args) {
$rv = ' (';
$first = true;
@@ -500,6 +505,7 @@ function format_args ($args) {
return $rv;
}
+# format doxygen documentation for class-definition
function format_doxyclass ($cl) {
$rv = '';
if (isset ($cl['decl'])) {
@@ -511,6 +517,7 @@ function format_doxyclass ($cl) {
return $rv;
}
+# format doxygen documentation for class-members
function format_doxydoc ($f) {
$rv = '';
if (isset ($f['cand'])) {
@@ -525,8 +532,16 @@ function format_doxydoc ($f) {
}
return $rv;
}
+
+# usort() callback for class-members
+function name_sort_cb ($a, $b) {
+ return strcmp ($a['name'], $b['name']);
+}
+
+# main output function for every class
function format_class_members ($ns, $cl, &$dups) {
$rv = '';
+ # print contructor - if any
if (isset ($cl['ctor'])) {
usort ($cl['ctor'], 'name_sort_cb');
$rv.= ' '.NL;
@@ -535,9 +550,14 @@ function format_class_members ($ns, $cl, &$dups) {
$rv.= ''.ctorname ($f['name']).'';
$rv.= format_args ($f['args']);
$rv.= 'Constructor
The top-level entry point are =typelink('ARDOUR:Session')?> and =typelink('ArdourUI:Editor')?>. @@ -693,7 +729,7 @@ If the C++ method also returns a value it is prefixed. Two parameters are return } -
local var = 0;
@@ -704,7 +740,7 @@ ref = set_ref (var, 2);
print (ref[1], ref[2])
5 7
- rv, ref = set_ref2 (0, "hello");
print (rv, ref[1], ref[2])
3 5 hello
- C‡: '.htmlentities ($cl['decl']).'
'.NL; } - # print class inheritance + # print class inheritance (direct parent *name* only) $inherited = array (); $isa = traverse_parent ($ns, $inherited); if (!empty ($isa)) { @@ -788,6 +835,8 @@ foreach ($classlist as $ns => $cl) { } echo ''.NL; + + # class documentation (if any) echo format_doxyclass ($cl); # member documentation @@ -799,7 +848,7 @@ foreach ($classlist as $ns => $cl) { echo ' '.NL; } - # traverse parent classes (inherited members) + # traverse parent classes (all inherited members) foreach ($inherited as $pns => $pcl) { $tbl = format_class_members ($pns, $pcl, $dups); if (!empty ($tbl)) { @@ -811,6 +860,9 @@ foreach ($classlist as $ns => $cl) { } } +#################### +# Enum and Constants + echo '