X-Git-Url: https://main.carlh.net/gitweb/?a=blobdiff_plain;f=tools%2Ffmt-luadoc.php;h=7f7b35d589c74084deb71a85cb4dd516611cead9;hb=f84a7605d8781df6f4d2214c636d9f438c93ae33;hp=f35b8293802d553561c251706fea8a44a565d213;hpb=dd27620566cf83631c309f008a5bc6b4c28b9f07;p=ardour.git

diff --git a/tools/fmt-luadoc.php b/tools/fmt-luadoc.php
index f35b829380..7f7b35d589 100755
--- a/tools/fmt-luadoc.php
+++ b/tools/fmt-luadoc.php
@@ -16,13 +16,27 @@
 # 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
+}
+
 ################################################################################
 ################################################################################
 
 $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;
+	}
+	# 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']));
@@ -114,13 +128,22 @@ function stripclass ($classname, $name) {
 function datatype ($decl) {
 	# TODO handle spaces in type. Works because
 	# we don't yet have templated types (with_space <here >)
-	return substr ($decl, 0, strpos ($decl, ' '));
+	return substr ($decl, 0, strrpos ($decl, ' '));
 }
 
 function luafn2class ($lua) {
 	return substr ($lua, 0, strrpos ($lua, ':'));
 }
 
+function luafn2name ($lua) {
+	$fn = strrpos ($lua, ':');
+	if ($fn !== 0 && strlen($lua) > $fn + 1) {
+		return substr ($lua, $fn + 1);
+	}
+	my_die ('invalid class prefix: '. $name);
+}
+
+
 function checkclass ($b) {
 	global $classlist;
 	if (!isset ($classlist[luafn2class ($b['lua'])])) {
@@ -245,6 +268,26 @@ foreach ($doc as $b) {
 			'ret'  => arg2lua (datatype ($b['ldec']))
 		);
 		break;
+	case "Static C Function":
+		checkclass ($b);
+		if (strpos ($b['lua'], 'ARDOUR:DataType:') === 0) {
+			# special case ARDOUR:DataType convenience c'tor
+			$args = array ();
+			$ret = array (luafn2class ($b['lua']) => 0);
+			$canon = 'ARDOUR::LuaAPI::datatype_ctor_'.strtolower (luafn2name ($b['lua'])).'(lua_State*)';
+		} else {
+			my_die ('unhandled Static C: ' . print_r($b, true));
+		}
+		$classlist[luafn2class ($b['lua'])]['func'][] = array (
+			'bind' => $b,
+			'name' => $b['lua'],
+			'args' => $args,
+			'ret'  => $ret,
+			'ref'  => false,
+			'ext'  => false,
+			'cand' => $canon
+		);
+		break;
 	case "C Function":
 		# we required C functions to be in a class namespace
 	case "Ext C Function":
@@ -253,9 +296,8 @@ foreach ($doc as $b) {
 		$ret = array ('...' => 0);
 		$ns = luafn2class ($b['lua']);
 		$cls = $classlist[$ns];
-		## std::Vector std::List types
 		if (preg_match ('/.*<([^>]*)[ ]*>/', $cls['ldec'], $templ)) {
-			// XXX -> move to C-source
+			# std::vector, std::list types
 			switch (stripclass($ns, $b['lua'])) {
 			case 'add':
 				#$args = array (array ('LuaTable {'.$templ[1].'}' => 0));
@@ -274,6 +316,7 @@ foreach ($doc as $b) {
 				break;
 			}
 		} else if (strpos ($cls['type'], ' Array') !== false) {
+			# catches  C:FloatArray, C:IntArray
 			$templ = preg_replace ('/[&*]*$/', '', $cls['ldec']);
 			switch (stripclass($ns, $b['lua'])) {
 			case 'array':
@@ -302,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 (
@@ -319,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 (
@@ -331,6 +384,18 @@ foreach ($doc as $b) {
 			'cand' => canonical_decl ($b)
 		);
 		break;
+	case "Cast":
+	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
@@ -350,14 +415,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'];
 			}
 		}
 	}
@@ -392,8 +460,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 +473,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;
@@ -413,14 +486,18 @@ function doxydoc ($canonical_declaration) {
 		$dox_found++;
 		return $api[$canonical_declaration]['doc'];
 	}
-	elseif (isset ($api['ARDOUR::'.$canonical_declaration])) {
+	// remove template namespace e.g.
+	//  "ARDOUR::Track::bounceable(boost::shared_ptr<ARDOUR::Processor>"
+	//  "ARDOUR::Track::bounceable(boost::shared_ptr<Processor>"
+	$cn = preg_replace ('/<[^>]*::([^>]*)>/', '<$1>', $canonical_declaration);
+	if (isset ($api[$cn])) {
 		$dox_found++;
-		return $api['ARDOUR::'.$canonical_declaration]['doc'];
-	}
-	else {
-		$dox_miss++;
-		return '';
+		return $api[$cn]['doc'];
 	}
+	#fwrite (STDERR, $canonical_declaration."\n"); # XXX DEBUG
+
+	$dox_miss++;
+	return '';
 }
 
 ################################################################################
@@ -432,22 +509,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 +541,11 @@ function traverse_parent ($ns, &$inherited) {
 	return $rv;
 }
 
+# create a cross-reference to a type (class or enum)
+# *all* <a> 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 '<a class="'.$linkcls.'" href="#'.htmlentities ($a).'">'.($short ? shortname($a) : ctorname($a)).$suffix.'</a>';
 	} else if (in_array ($a, array_keys ($classlist))) {
@@ -480,6 +557,7 @@ function typelink ($a, $short = false, $argcls = '', $linkcls = '', $suffix = ''
 	}
 }
 
+# output format function arguments
 function format_args ($args) {
 	$rv = '<span class="functionargs"> (';
 	$first = true;
@@ -500,6 +578,7 @@ function format_args ($args) {
 	return $rv;
 }
 
+# format doxygen documentation for class-definition
 function format_doxyclass ($cl) {
 	$rv = '';
 	if (isset ($cl['decl'])) {
@@ -511,6 +590,7 @@ function format_doxyclass ($cl) {
 	return $rv;
 }
 
+# format doxygen documentation for class-members
 function format_doxydoc ($f) {
 	$rv = '';
 	if (isset ($f['cand'])) {
@@ -525,8 +605,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.= ' <tr><th colspan="3">Constructor</th></tr>'.NL;
@@ -535,9 +623,14 @@ function format_class_members ($ns, $cl, &$dups) {
 			$rv.= '<span class="functionname">'.ctorname ($f['name']).'</span>';
 			$rv.= format_args ($f['args']);
 			$rv.= '</td><td class="fill"></td></tr>'.NL;
+			# doxygen documentation (may be empty)
 			$rv.= format_doxydoc($f);
 		}
 	}
+
+	# strip duplicates (inherited or derived methods)
+	# e.g  AudioTrack -> Track -> Route -> SessionObject -> Stateful
+	# all 5 have "isnil()"
 	$nondups = array ();
 	if (isset ($cl['func'])) {
 		foreach ($cl['func'] as $f) {
@@ -545,30 +638,55 @@ function format_class_members ($ns, $cl, &$dups) {
 			$nondups[] = $f;
 		}
 	}
+
+	# print methods - if any
 	if (count ($nondups) > 0) {
 		usort ($nondups, 'name_sort_cb');
 		$rv.= ' <tr><th colspan="3">Methods</th></tr>'.NL;
 		foreach ($nondups as $f) {
 			$dups[] = stripclass ($ns, $f['name']);
+			# return value/type
 			$rv.= ' <tr><td class="def">';
 			if ($f['ref'] && isset ($f['ext'])) {
 				# external C functions
 				$rv.= '<em>'.varname ($f['ret']).'</em>';
 			} elseif ($f['ref'] && varname ($f['ret']) == 'void') {
-				# functions with reference args return args
+				# void functions with reference args
 				$rv.= '<em>LuaTable</em>(...)';
 			} elseif ($f['ref']) {
+				# functions with reference args and return value
 				$rv.= '<em>LuaTable</em>('.typelink (varname ($f['ret']), true, 'em').', ...)';
 			} else {
+				# normal class members
 				$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 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');
 		$rv.= ' <tr><th colspan="3">Data Members</th></tr>'.NL;
@@ -585,58 +703,62 @@ function format_class_members ($ns, $cl, &$dups) {
 ################################################################################
 # Start Output
 
+if ($HTMLOUTPUT) {
+
 ?><!DOCTYPE html>
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
 <head>
 <title>Ardour Lua Bindings</title>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
 <style type="text/css">
-div.content        { max-width:60em; margin: 1em auto; }
-h1                 { margin:2em 0 0 0; padding:0em; border-bottom: 1px solid black;}
-h2.cls             { margin:2em 0 0 0; padding-left:1em; border: 1px dashed #6666ee;}
-h2.cls abbr        { text-decoration:none; cursor:default;}
-h3.cls             { margin:1em 0 0 0;}
-h2.class           { background-color: #aaee66; }
-h2.enum            { background-color: #aaaaaa; }
-h2.pointerclass    { background-color: #eeaa66; }
-h2.array           { background-color: #66aaee; }
-h2.opaque          { background-color: #6666aa; }
-p                  { text-align: justify; }
-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.code           { width:80%; margin:.5em auto; }
-div.code div       { width:45%; }
-div.code pre       { line-height: 1.2em; margin: .25em 0; }
-div.code samp      { color: green; font-weight: bold; background-color: #eee; }
-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:#eee; 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;}
-div.header         {text-align:center;}
-div.header h1      {margin:0;}
-div.header p       {margin:.25em; text-align:center;}
+div.header         { text-align:center; }
+div.header h2      { margin:0; }
+div.header p       { margin:.25em; text-align:center; }
+div.luafooter      { text-align:center; font-size:80%; color: #888; margin: 2em 0; }
+#luaref            { max-width:60em; margin: 1em auto; }
+
+#luaref h2                 { margin:2em 0 0 0; padding:0em; border-bottom: 1px solid black; }
+#luaref h3.cls             { margin:2em 0 0 0; padding: 0 0 0 1em; border: 1px dashed #6666ee; }
+#luaref h3.cls abbr        { text-decoration:none; cursor:default; }
+#luaref h4.cls             { margin:1em 0 0 0; }
+#luaref h3.class           { background-color: #aaee66; }
+#luaref h3.enum            { background-color: #aaaaaa; }
+#luaref h3.pointerclass    { background-color: #eeaa66; }
+#luaref h3.array           { background-color: #66aaee; }
+#luaref h3.opaque          { background-color: #6666aa; }
+#luaref p                  { text-align: justify; }
+#luaref p.cdecl            { text-align: right; float:right; font-size:90%; margin:0; padding: 0 0 0 1em; }
+#luaref ul.classindex      { columns: 2; -webkit-columns: 2; -moz-columns: 2; }
+#luaref div.clear          { clear:both; }
+#luaref p.classinfo        { margin: .25em 0; }
+#luaref div.code           { width:80%; margin:.5em auto; }
+#luaref div.code div       { width:45%; }
+#luaref div.code pre       { line-height: 1.2em; margin: .25em 0; }
+#luaref div.code samp      { color: green; font-weight: bold; background-color: #eee; }
+#luaref div.classdox       { padding: .1em 1em; }
+#luaref div.classdox p     { margin: .5em 0 .5em .6em; }
+#luaref div.classdox p     { margin: .5em 0 .5em .6em; }
+#luaref div.classdox       { padding: .1em 1em; }
+#luaref div.classdox p     { margin: .5em 0 .5em .6em; }
+#luaref table.classmembers { width: 100%; }
+#luaref table.classmembers th      { text-align:left; border-bottom:1px solid black; padding-top:1em; }
+#luaref table.classmembers td.def  { text-align:right; padding-right:.5em;  white-space: nowrap; }
+#luaref table.classmembers td.decl { text-align:left; padding-left:.5em; white-space: nowrap; }
+#luaref table.classmembers td.doc  { text-align:left; padding-left:.6em; line-height: 1.2em; font-size:80%; }
+#luaref table.classmembers td.doc div.dox {background-color:#eee; padding: .1em 1em; }
+#luaref table.classmembers td.doc p { margin: .5em 0; }
+#luaref table.classmembers td.doc p.para-brief { font-size:120%; }
+#luaref table.classmembers td.doc p.para-returns { font-size:120%; }
+#luaref table.classmembers td.doc dl { font-size:120%; line-height: 1.3em; }
+#luaref table.classmembers td.doc dt { font-style: italic; }
+#luaref table.classmembers td.fill { width: 99%; }
+#luaref table.classmembers span.em { font-style: italic; }
+#luaref span.functionname abbr     { text-decoration:none; cursor:default; }
 </style>
 </head>
 <body>
 <div class="header">
-<h1>Ardour Lua Bindings</h1>
+<h2>Ardour Lua Bindings</h2>
 <p>
 <a href="#h_classes">Class Documentation</a>
 &nbsp;|&nbsp;
@@ -645,9 +767,38 @@ div.header p       {margin:.25em; text-align:center;}
 <a href="#h_index">Index</a>
 </p>
 </div>
-<div class="content">
 
-<h1 id="h_intro">Overview</h1>
+<!-- #### SNIP #### !-->
+
+<?php
+
+} else {
+
+?>
+---
+layout: default
+style: luadoc
+title: Class Reference
+---
+
+<p class="warning">
+This documentation is far from complete may be inaccurate and subject to change.
+</p>
+
+<?php
+}
+?>
+
+<div id="luaref">
+
+<?php
+
+################################################################################
+# some general documentation -- should really go elsehere
+
+?>
+
+<h2 id="h_intro">Overview</h2>
 <p>
 The top-level entry point are <?=typelink('ARDOUR:Session')?> and <?=typelink('ArdourUI:Editor')?>.
 Most other Classes are used indirectly starting with a Session function. e.g. Session:get_routes().
@@ -660,7 +811,7 @@ A few classes are dedicated to certain script types, e.g. Lua DSP processors hav
 <p>
 Detailed documentation (parameter names, method description) is not yet available. Please stay tuned.
 </p>
-<h2>Short introduction to Ardour classes</h2>
+<h3>Short introduction to Ardour classes</h3>
 <p>
 Ardour's structure is object oriented. The main object is the Session. A Session contains Audio Tracks, Midi Tracks and Busses.
 Audio and Midi tracks are derived from a more general "Track" Object,  which in turn is derived from a "Route" (aka Bus).
@@ -672,10 +823,16 @@ 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>
-<h2>Pass by Reference</h2>
+<h3>Pass by Reference</h3>
 <p>
 Since lua functions are closures, C++ methods that pass arguments by reference cannot be used as-is.
 All parameters passed to a C++ method which uses references are returned as Lua Table.
@@ -693,7 +850,7 @@ If the C++ method also returns a value it is prefixed. Two parameters are return
 }
 </code></pre>
 
-  </div>
+	</div>
 	<div style="float:right;">Lua
 
 <pre><code class="lua">local var = 0;
@@ -704,7 +861,7 @@ ref = set_ref (var, 2);
 print (ref[1], ref[2])
 </code><samp class="lua">5 7</samp></pre>
 
-  </div>
+	</div>
 </div>
 <div class="clear"></div>
 <div class="code">
@@ -717,16 +874,16 @@ print (ref[1], ref[2])
 }
 </code></pre>
 
-  </div>
-  <div style="float:right;">
+	</div>
+	<div style="float:right;">
 <pre><code class="lua">rv, ref = set_ref2 (0, "hello");
 print (rv, ref[1], ref[2])
 </code><samp class="lua">3 5 hello</samp></pre>
-  </div>
+	</div>
 </div>
 <div class="clear"></div>
 
-<h2>Pointer Classes</h2>
+<h3>Pointer Classes</h3>
 <p>
 Libardour makes extensive use of reference counted <code>boost::shared_ptr</code> to manage lifetimes.
 The Lua bindings provide a complete abstration of this. There are no pointers in lua.
@@ -755,32 +912,43 @@ Pointer Classes cannot be created in lua scripts. It always requires a call to C
 
 
 <?php
-echo '<h1 id="h_classes">Class Documentation</h1>'.NL;
 
+#################################
+# Main output function -- Classes
+
+echo '<h2 id="h_classes">Class Documentation</h2>'.NL;
 foreach ($classlist as $ns => $cl) {
 	$dups = array ();
 	$tbl =  format_class_members ($ns, $cl, $dups);
 
-	# format class title
+	# format class title - depending on type
 	if (empty ($tbl)) {
-		echo '<h2 id="'.htmlentities ($ns).'" class="cls opaque"><abbr title="Opaque Object">&empty;</abbr>&nbsp;'.htmlentities ($ns).'</h2>'.NL;
+		# classes with no members (no ctor, no methods, no data)
+		echo '<h3 id="'.htmlentities ($ns).'" class="cls opaque"><abbr title="Opaque Object">&empty;</abbr>&nbsp;'.htmlentities ($ns).'</h3>'.NL;
 	}
 	else if (isset ($classlist[$ns]['free'])) {
-		echo '<h2 id="'.htmlentities ($ns).'" class="cls freeclass"><abbr title="Namespace">&Nopf;</abbr>&nbsp;'.ctorname($ns).'</h2>'.NL;
+		# free functions (no class)
+		echo '<h3 id="'.htmlentities ($ns).'" class="cls freeclass"><abbr title="Namespace">&Nopf;</abbr>&nbsp;'.ctorname($ns).'</h3>'.NL;
 	}
 	else if (isset ($classlist[$ns]['arr'])) {
-		echo '<h2 id="'.htmlentities ($ns).'" class="cls array"><abbr title="C Array">&ctdot;</abbr>&nbsp;'.htmlentities ($ns).'</h2>'.NL;
+		# C Arrays
+		echo '<h3 id="'.htmlentities ($ns).'" class="cls array"><abbr title="C Array">&ctdot;</abbr>&nbsp;'.htmlentities ($ns).'</h3>'.NL;
 	}
 	else if (isset ($classlist[$ns]['ptr'])) {
-		echo '<h2 id="'.htmlentities ($ns).'" class="cls pointerclass"><abbr title="Pointer Class">&Rarr;</abbr>&nbsp;'. htmlentities ($ns).'</h2>'.NL;
-	} else {
-		echo '<h2 id="'.htmlentities ($ns).'" class="cls class"><abbr title="Class">&comp;</abbr>&nbsp;'.htmlentities ($ns).'</h2>'.NL;
+		# Pointer Classes
+		echo '<h3 id="'.htmlentities ($ns).'" class="cls pointerclass"><abbr title="Pointer Class">&Rarr;</abbr>&nbsp;'. htmlentities ($ns).'</h3>'.NL;
 	}
-	if (isset ($cl['decl'])) {
-		echo '<p class="cdecl"><em>C&#8225;</em>: '.htmlentities ($cl['decl']).'</p>'.NL;
+	else {
+		# Normal Class
+		echo '<h3 id="'.htmlentities ($ns).'" class="cls class"><abbr title="Class">&comp;</abbr>&nbsp;'.htmlentities ($ns).'</h3>'.NL;
+	}
+
+	# show original C++ declaration
+	if (isset ($cl['cdecl'])) {
+		echo '<p class="cdecl"><em>C&#8225;</em>: '.htmlentities ($cl['cdecl']).'</p>'.NL;
 	}
 
-	# print class inheritance
+	# print class inheritance (direct parent *name* only)
 	$inherited = array ();
 	$isa = traverse_parent ($ns, $inherited);
 	if (!empty ($isa)) {
@@ -788,6 +956,8 @@ foreach ($classlist as $ns => $cl) {
 	}
 	echo '<div class="clear"></div>'.NL;
 
+
+	# class documentation (if any)
 	echo format_doxyclass ($cl);
 
 	# member documentation
@@ -799,11 +969,11 @@ foreach ($classlist as $ns => $cl) {
 		echo ' </table>'.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)) {
-			echo '<h3 class="cls">Inherited from '.$pns.'</h3>'.NL;
+			echo '<h4 class="cls">Inherited from '.$pns.'</h4>'.NL;
 			echo '<table class="classmembers">'.NL;
 			echo $tbl;
 			echo '</table>'.NL;
@@ -811,9 +981,12 @@ foreach ($classlist as $ns => $cl) {
 	}
 }
 
-echo '<h1 id="h_enum">Enum/Constants</h1>'.NL;
+####################
+# Enum and Constants
+
+echo '<h2 id="h_enum">Enum/Constants</h2>'.NL;
 foreach ($constlist as $ns => $cs) {
-	echo '<h2 id="'.ctorname ($ns).'" class="cls enum"><abbr title="Enum">&isin;</abbr>&nbsp;'.ctorname ($ns).'</h2>'.NL;
+	echo '<h3 id="'.ctorname ($ns).'" class="cls enum"><abbr title="Enum">&isin;</abbr>&nbsp;'.ctorname ($ns).'</h3>'.NL;
 	echo '<ul class="enum">'.NL;
 	foreach ($cs as $c) {
 		echo '<li class="const">'.ctorname ($c['lua']).'</li>'.NL;
@@ -821,15 +994,28 @@ foreach ($constlist as $ns => $cs) {
 	echo '</ul>'.NL;
 }
 
-echo '<h1 id="h_index" >Class Index</h1>'.NL;
+######################
+# Index of all classes
+
+echo '<h2 id="h_index" >Class Index</h2>'.NL;
 echo '<ul class="classindex">'.NL;
 foreach ($classlist as $ns => $cl) {
 	echo '<li>'.typelink($ns).'</li>'.NL;
 }
 echo '</ul>'.NL;
 
+
+# see how far there is still to go...
 fwrite (STDERR, "Found $dox_found annotations. missing: $dox_miss\n");
+echo '<!-- '.$dox_found.' / '.$dox_miss.' !-->'.NL;
+
 ?>
 </div>
-</body>
-</html>
+<div class="luafooter">Ardour <?=$ardourversion?> &nbsp;-&nbsp; <?=date('r')?></div>
+<?php
+
+if ($HTMLOUTPUT) {
+	echo '<!-- #### SNIP #### !-->'.NL;
+	echo '</body>'.NL;
+	echo '</html>'.NL;
+}