Improve documentation

11 files changed, 31 insertions, 25 deletions

diff --git a/bundles/ingen.lv2/ingen.ttl b/bundles/ingen.lv2/ingen.ttl
index d1a4cc2c..4d4ddf69 100644
--- a/bundles/ingen.lv2/ingen.ttl
+++ b/bundles/ingen.lv2/ingen.ttl
@@ -11,9 +11,9 @@
 ingen:
 	a owl:Ontology ;
 	owl:imports <http://lv2plug.in/ns/lv2core> ;
-	doap:name "Ingen Ontology" ;
-	rdfs:label "Ingen Ontology" ;
-	rdfs:comment "Describes graphs of signal processing blocks which process audio, MIDI, and other signals or messages.  With appropriate plugins, these graphs can describe modular synthesizers, effects processors, and other signal processing devices." .
+	doap:name "Ingen" ;
+	rdfs:label "Ingen" ;
+	rdfs:comment "Ingen is a modular audio processing environment.  This vocabulary describes an Ingen configuration, and is used in both the control protocol and saved files.  Conceptually, Ingen represents a tree of objects, each of which has a path (like /main/in or /main/osc/out) and a set of properties." .
 
 ingen:Plugin
 	a rdfs:Class ;
diff --git a/ingen/AtomSink.hpp b/ingen/AtomSink.hpp
index 8228001e..d5fe775c 100644
--- a/ingen/AtomSink.hpp
+++ b/ingen/AtomSink.hpp
@@ -31,6 +31,7 @@ public:
 
 	/** Write an Atom to the sink.
 	 *
+	 * @param msg The atom to write.
 	 * @param default_id The default response ID to use if no
 	 * patch:sequenceNumber property is present on the message.
 	 *
diff --git a/ingen/EngineBase.hpp b/ingen/EngineBase.hpp
index 7ba4467a..087189e4 100644
--- a/ingen/EngineBase.hpp
+++ b/ingen/EngineBase.hpp
@@ -28,7 +28,7 @@ namespace Ingen {
 class Interface;
 
 /**
-   The engine which executes the process graph.
+   The audio engine which executes the graph.
 
    @ingroup Ingen
 */
diff --git a/ingen/Interface.hpp b/ingen/Interface.hpp
index a1a93c06..8a79f269 100644
--- a/ingen/Interface.hpp
+++ b/ingen/Interface.hpp
@@ -37,8 +37,7 @@ class URI;
 
 namespace Ingen {
 
-/** Abstract interface common to both engine and clients.
- * Purely virtual (except for the destructor).
+/** Abstract interface for Ingen servers and clients.
  *
  * @ingroup Ingen
  */
diff --git a/ingen/Node.hpp b/ingen/Node.hpp
index d6253cc4..72c0b3cb 100644
--- a/ingen/Node.hpp
+++ b/ingen/Node.hpp
@@ -34,7 +34,7 @@ namespace Ingen {
 class Arc;
 class Store;
 
-/** An object on the audio graph.
+/** A node in the audio graph.
  *
  * The key property of nodes is that all nodes have a path and a symbol, as
  * well as a URI.
diff --git a/ingen/Parser.hpp b/ingen/Parser.hpp
index 050ddb5a..d6065e59 100644
--- a/ingen/Parser.hpp
+++ b/ingen/Parser.hpp
@@ -34,7 +34,7 @@ class Interface;
 class World;
 
 /**
-   Read Ingen objects from Turtle files or strings.
+   Parser for reading graphs from Turtle files or strings.
 
    @ingroup Ingen
 */
diff --git a/ingen/Resource.hpp b/ingen/Resource.hpp
index 604428ce..39452522 100644
--- a/ingen/Resource.hpp
+++ b/ingen/Resource.hpp
@@ -28,7 +28,11 @@
 
 namespace Ingen {
 
-/** An object with a URI described by properties.
+/** A resource with a URI described by properties.
+ *
+ * This is the base class for most things in Ingen, including graphs, blocks,
+ * ports, and the engine itself.
+ *
  * @ingroup Ingen
  */
 class INGEN_API Resource : public Raul::Deletable
diff --git a/ingen/Serialiser.hpp b/ingen/Serialiser.hpp
index b02cd070..e1a62f6e 100644
--- a/ingen/Serialiser.hpp
+++ b/ingen/Serialiser.hpp
@@ -33,7 +33,7 @@ class Store;
 class World;
 
 /**
-   Write Ingen objects to Turtle files or strings.
+   Serialiser for writing graphs to Turtle files or strings.
 
    @ingroup Ingen
 */
diff --git a/src/AtomWriter.cpp b/src/AtomWriter.cpp
index f2687fab..f477adcc 100644
--- a/src/AtomWriter.cpp
+++ b/src/AtomWriter.cpp
@@ -113,6 +113,13 @@ AtomWriter::finish_msg()
  * @code{.ttl}
  * [] a ingen:BundleStart .
  * @endcode
+
+ * An [ingen:BundleEnd](http://drobilla.net/ns/ingen#BundleEnd) marks the end
+ * of a bundle in the operation stream.
+ *
+ * @code{.ttl}
+ * [] a ingen:BundleEnd .
+ * @endcode
  */
 void
 AtomWriter::bundle_begin()
@@ -123,15 +130,6 @@ AtomWriter::bundle_begin()
 	finish_msg();
 }
 
-/** @page protocol
- *
- * An [ingen:BundleEnd](http://drobilla.net/ns/ingen#BundleEnd) marks the end
- * of a bundle in the operation stream.
- *
- * @code{.ttl}
- * [] a ingen:BundleEnd .
- * @endcode
- */
 void
 AtomWriter::bundle_end()
 {
diff --git a/src/server/RunContext.hpp b/src/server/RunContext.hpp
index eba30545..feeb4874 100644
--- a/src/server/RunContext.hpp
+++ b/src/server/RunContext.hpp
@@ -49,6 +49,8 @@ class RunContext
 public:
 	/** Create a new run context.
 	 *
+	 * @param engine The engine this context is running within.
+	 * @param id The ID of this context.
 	 * @param threaded If true, then this context is a worker which will launch
 	 * a thread and execute tasks as they become available.
 	 */
diff --git a/wscript b/wscript
index daf859e4..79f6a80c 100644
--- a/wscript
+++ b/wscript
@@ -241,9 +241,14 @@ def build(bld):
     bld.install_files('${BINDIR}', 'scripts/ingenish', chmod=Utils.O755)
     bld.install_files('${BINDIR}', 'scripts/ingenams', chmod=Utils.O755)
 
-    # Documentation
+    # Code documentation
     autowaf.build_dox(bld, 'INGEN', INGEN_VERSION, top, out)
 
+    # Ontology documentation
+    bld(rule='lv2specgen.py ${SRC} ${TGT} -i -p ingen --copy-style --list-email ingen@drobilla.net --list-page http://lists.drobilla.net/listinfo.cgi/ingen-drobilla.net',
+        source = 'bundles/ingen.lv2/ingen.ttl',
+        target = 'ingen.lv2/ingen.html')
+
     # Man page
     bld.install_files('${MANDIR}/man1', 'doc/ingen.1')
 
@@ -279,12 +284,9 @@ def upload_docs(ctx):
     import shutil
 
     # Ontology documentation
-    specgendir = '/usr/local/share/lv2specgen/'
-    shutil.copy(specgendir + 'style.css', 'build')
-    os.system('lv2specgen.py --list-email=ingen@drobilla.net --list-page=http://lists.drobilla.net/listinfo.cgi/ingen-drobilla.net bundles/ingen.lv2/ingen.ttl %s style.css build/ingen.html' % specgendir)
     os.system('rsync -avz -e ssh bundles/ingen.lv2/ingen.ttl drobilla@drobilla.net:~/drobilla.net/ns/')
-    os.system('rsync -avz -e ssh build/ingen.html drobilla@drobilla.net:~/drobilla.net/ns/')
-    os.system('rsync -avz -e ssh %s/style.css drobilla@drobilla.net:~/drobilla.net/ns/' % specgendir)
+    os.system('rsync -avz -e ssh build/ingen.lv2/ingen.html drobilla@drobilla.net:~/drobilla.net/ns/')
+    os.system('rsync -avz -e ssh build/ingen.lv2/style.css drobilla@drobilla.net:~/drobilla.net/ns/')
 
     # Doxygen documentation
     os.system('rsync -ravz --delete -e ssh build/doc/html/* drobilla@drobilla.net:~/drobilla.net/docs/ingen/')