Improve documentation.

git-svn-id: http://svn.drobilla.net/lad/trunk/slv2@3110 a436a847-0d15-0410-975c-d299462d15a1

4 files changed, 66 insertions, 50 deletions

diff --git a/doc/reference.doxygen.in b/doc/reference.doxygen.in
index e55fa28..7d92ff0 100644
--- a/doc/reference.doxygen.in
+++ b/doc/reference.doxygen.in
@@ -74,7 +74,7 @@ BRIEF_MEMBER_DESC      = NO
 # Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
 # brief descriptions will be completely suppressed.
 
-REPEAT_BRIEF           = NO
+REPEAT_BRIEF           = YES
 
 # This tag implements a quasi-intelligent brief description abbreviator
 # that is used to form the text in various listings. Each string
@@ -270,7 +270,7 @@ SUBGROUPING            = YES
 # be useful for C code in case the coding convention dictates that all compound
 # types are typedef'ed and only the typedef is referenced, never the tag name.
 
-TYPEDEF_HIDES_STRUCT   = NO
+TYPEDEF_HIDES_STRUCT   = YES
 
 # The SYMBOL_CACHE_SIZE determines the size of the internal cache use to
 # determine which symbols to keep in memory and which to flush to disk.
@@ -297,7 +297,7 @@ SYMBOL_CACHE_SIZE      = 0
 # Private class members and static file members will be hidden unless
 # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
 
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
 
 # If the EXTRACT_PRIVATE tag is set to YES all private members of a class
 # will be included in the documentation.
@@ -480,14 +480,14 @@ SHOW_DIRECTORIES       = NO
 # This will remove the Files entry from the Quick Index and from the
 # Folder Tree View (if specified). The default is YES.
 
-SHOW_FILES             = YES
+SHOW_FILES             = NO
 
 # Set the SHOW_NAMESPACES tag to NO to disable the generation of the
 # Namespaces page.
 # This will remove the Namespaces entry from the Quick Index
 # and from the Folder Tree View (if specified). The default is YES.
 
-SHOW_NAMESPACES        = YES
+SHOW_NAMESPACES        = NO
 
 # The FILE_VERSION_FILTER tag can be used to specify a program or script that
 # doxygen should invoke to get the current version for each file (typically from
@@ -506,7 +506,7 @@ FILE_VERSION_FILTER    =
 # file name after the option, if omitted DoxygenLayout.xml will be used as the name
 # of the layout file.
 
-LAYOUT_FILE            =
+LAYOUT_FILE            = @SLV2_SRCDIR@/doc/layout.xml
 
 #---------------------------------------------------------------------------
 # configuration options related to warning and progress messages
@@ -527,7 +527,7 @@ WARNINGS               = YES
 # for undocumented members. If EXTRACT_ALL is set to YES then this flag will
 # automatically be disabled.
 
-WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_UNDOCUMENTED   = YES
 
 # If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
 # potential errors in the documentation, such as not documenting some
@@ -1352,7 +1352,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # toolkit from AT&T and Lucent Bell Labs. The other options in this section
 # have no effect if this option is set to NO (the default)
 
-HAVE_DOT               = YES
+HAVE_DOT               = NO
 
 # By default doxygen will write a font called FreeSans.ttf to the output
 # directory and reference it in all dot files that doxygen generates. This
@@ -1412,14 +1412,14 @@ TEMPLATE_RELATIONS     = NO
 # file showing the direct and indirect include dependencies of the file with
 # other documented files.
 
-INCLUDE_GRAPH          = YES
+INCLUDE_GRAPH          = NO
 
 # If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and
 # HAVE_DOT tags are set to YES then doxygen will generate a graph for each
 # documented header file showing the documented files that directly or
 # indirectly include this file.
 
-INCLUDED_BY_GRAPH      = YES
+INCLUDED_BY_GRAPH      = NO
 
 # If the CALL_GRAPH and HAVE_DOT options are set to YES then
 # doxygen will generate a call dependency graph for every global function
diff --git a/doc/style.css b/doc/style.css
index 8e84c8b..82239a2 100644
--- a/doc/style.css
+++ b/doc/style.css
@@ -7,35 +7,32 @@ body {
 	display: none;
 }
 
+h1 h2 h3 h4 h5 h6 {
+	font-weight: bold;
+}
+
 h1 {
-	font-size: 180%;
-	font-weight: 900;
+	font-size: 164%;
 }
 
 h2 {
-	font-size: 140%;
-	font-weight: 650;
+	font-size: 132%;
 }
 
 h3 {
-	font-size: 130%;
-	font-weight: 600;
-
+	font-size: 124%;
 }
 
 h4 {
-	font-size: 120%;
-	font-weight: 550;
+	font-size: 116%;
 }
 
 h5 {
-	font-size: 110%;
-	font-weight: 500;
+	font-size: 108%;
 }
 
 h6 {
 	font-size: 100%;
-	font-weight: 450;
 }
 
 p {
@@ -103,7 +100,6 @@ div.navtab {
 /* @group Link Styling */
 a {
 	color: #3D578C;
-	font-weight: 400;
 	text-decoration: none;
 }
 
@@ -116,18 +112,15 @@ a:hover {
 }
 
 a.qindex {
-	font-weight: 700;
 }
 
 a.qindexHL {
-	font-weight: 700;
 	background-color: #9CAFD4;
 	color: #FFF;
 	border: 1px double #869DCA;
 }
 
 a.el {
-	font-weight: 700;
 }
 
 a.elRef {
@@ -317,6 +310,7 @@ hr.footer {
 /* @group Member Descriptions */
 table.memberdecls {
 	border-spacing: 0;
+	font-size: 94%;
 }
 
 .mdescLeft,.mdescRight,.memItemLeft,.memItemRight,.memTemplItemLeft,.memTemplItemRight,.memTemplParams {
@@ -349,7 +343,7 @@ table.memberdecls {
 .memtemplate {
 	font-size: 80%;
 	color: #4665A2;
-	font-weight: 400;
+	font-weight: bold;
 }
 
 .memnav {
@@ -368,14 +362,14 @@ table.memberdecls {
 
 .memname {
 	white-space: nowrap;
-	font-weight: 700;
+	font-weight: bold;
 }
 
 .memproto {
 	border-top: 1px solid #DDD;
 	padding: 0.5ex;
 	color: #253555;
-	font-weight: 700;
+	font-weight: bold;
 	background-color: #F3F3F3;
 }
 
@@ -413,7 +407,7 @@ table.memberdecls {
 /* these are for tree view when used as main index */
 .directory {
 	font-size: 9pt;
-	font-weight: 700;
+	font-weight: bold;
 	margin: 5px;
 }
 
@@ -444,7 +438,7 @@ table.memberdecls {
 /* these are for tree view when not used as main index */
 .directory-alt {
 	font-size: 100%;
-	font-weight: 700;
+	font-weight: bold;
 }
 
 .directory-alt h3 {
@@ -483,20 +477,21 @@ address {
 
 table.doxtable {
 	border-collapse: collapse;
+	margin: 0.5ex;
 }
 
 table.doxtable td,table.doxtable th {
-	border: 1px solid #2D4068;
+	border: 1px solid #DDD;
 	padding: 3px 7px 2px;
 }
 
 table.doxtable th {
-	background-color: #374F7F;
-	color: #FFF;
-	font-size: 110%;
+	background-color: #F3F3F3;
+	color: #000;
 	padding-bottom: 4px;
 	padding-top: 5px;
 	text-align: left;
+	font-weight: bold;
 }
 
 .tabsearch {
diff --git a/slv2/slv2.h b/slv2/slv2.h
index 5536740..52da71b 100644
--- a/slv2/slv2.h
+++ b/slv2/slv2.h
@@ -83,6 +83,16 @@ typedef struct _SLV2ScalePoint*   SLV2ScalePoint;   /**< Scale Point (Notch). */
 typedef struct _SLV2UI*           SLV2UI;           /**< Plugin UI. */
 typedef struct _SLV2Value*        SLV2Value;        /**< Typed Value. */
 typedef struct _SLV2World*        SLV2World;        /**< SLV2 World. */
+typedef struct _SLV2UIInstance*   SLV2UIInstance;   /**< Plugin UI Instance. */
+
+/**
+   A UI host descriptor.
+
+   A UI host descriptor contains the various functions that a plugin UI may use
+   to communicate with the plugin. It is passed to @ref slv2_ui_instance_new to
+   provide these functions to the UI.
+*/
+typedef struct _SLV2UIHost* SLV2UIHost;
 
 typedef void* SLV2PluginClasses;  /**< set<PluginClass>. */
 typedef void* SLV2Plugins;        /**< set<Plugin>. */
@@ -305,11 +315,12 @@ slv2_value_as_bool(SLV2Value value);
    <li>SLV2UIs (function prefix "slv2_uis_")</li>
    </ul>
 
-   Each collection type supports the following functions:
+   Each collection type supports a similar basic API:
    <ul>
-   <li>PREFIX_free (coll)</li>
-   <li>PREFIX_size (coll)</li>
-   <li>PREFIX_get_at (coll, index)</li>
+   <li>void PREFIX_free (coll)</li>
+   <li>unsigned PREFIX_size (coll)</li>
+   <li>SLV2Iter PREFIX_begin (coll)</li>
+   <li>ELEM PREFIX_get_at (coll, index)  (DEPRECATED)</li>
    </ul>
    @{
 */
@@ -318,10 +329,12 @@ slv2_value_as_bool(SLV2Value value);
 
 typedef void* SLV2Iter;
 
+/** Increment @a i to point at the next element in the collection. */
 SLV2_API
 SLV2Iter
 slv2_iter_next(SLV2Iter i);
 
+/** Return true iff @a i is at the end of the collection. */
 SLV2_API
 bool
 slv2_iter_end(SLV2Iter i);
@@ -1132,6 +1145,10 @@ slv2_plugin_class_get_children(SLV2PluginClass plugin_class);
 
 typedef struct _SLV2InstanceImpl* SLV2InstanceImpl;
 
+/**
+   @cond 0
+*/
+
 /* Instance of a plugin.
    This is exposed in the ABI to allow inlining of performance critical
    functions like slv2_instance_run (simple wrappers of functions in lv2.h).
@@ -1146,6 +1163,10 @@ typedef struct _Instance {
 }* SLV2Instance;
 
 /**
+   @endcond
+*/
+
+/**
    Instantiate a plugin.
    The returned value is a lightweight handle for an LV2 plugin instance,
    it does not refer to @a plugin, or any other SLV2 state.  The caller must
@@ -1377,8 +1398,6 @@ slv2_ui_get_binary_uri(SLV2UI ui);
    @{
 */
 
-typedef struct _SLV2UIInstance* SLV2UIInstance;
-
 /**
    DEPRECATED: Instantiate a plugin UI.
    This function is deprecated, it does not support widget wrapping.
@@ -1393,15 +1412,6 @@ slv2_ui_instantiate(SLV2Plugin                plugin,
                     LV2UI_Controller          controller,
                     const LV2_Feature* const* features);
 
-/**
-   A UI host descriptor.
-
-   A UI host descriptor contains the various functions that a plugin UI may
-   use to communicate with the plugin. It is passed to @ref
-   slv2_ui_instance_new to provide these functions to the UI.
-*/
-typedef struct _SLV2UIHost* SLV2UIHost;
-
 typedef uint32_t (*SLV2PortIndexFunction)(LV2UI_Controller controller,
                                           const char*      port_symbol);
 
diff --git a/wscript b/wscript
index 665943a..b5b0c9c 100644
--- a/wscript
+++ b/wscript
@@ -1,4 +1,5 @@
 #!/usr/bin/env python
+import os
 import sys
 
 import waflib.Options as Options
@@ -277,6 +278,16 @@ def build(bld):
 
 	bld.add_post_fun(autowaf.run_ldconfig)
 
+def fixdocs(ctx):
+    try:
+        os.system("sed -i 's/SLV2_API //' build/doc/html/group__slv2.html")
+        os.system("sed -i 's/SLV2_DEPRECATED //' build/doc/html/group__slv2.html")
+        os.remove('build/doc/html/index.html')
+        os.symlink('build/doc/html/group__slv2.html',
+                   'build/doc/html/index.html')
+    except:
+        Logs.error("Failed to fix up Doxygen documentation\n")
+
 def test(ctx):
 	autowaf.pre_test(ctx, APPNAME)
 	autowaf.run_tests(ctx, APPNAME, ['test/slv2_test'], dirs=['./src','./test'])