From e1c4f613c1554c93257667420b06c5729bb9edcd Mon Sep 17 00:00:00 2001 From: David Robillard Date: Thu, 17 Mar 2011 20:01:11 +0000 Subject: Improve documentation. git-svn-id: http://svn.drobilla.net/lad/trunk/slv2@3110 a436a847-0d15-0410-975c-d299462d15a1 --- doc/reference.doxygen.in | 20 ++++++++++---------- doc/style.css | 45 ++++++++++++++++++++------------------------- slv2/slv2.h | 40 +++++++++++++++++++++++++--------------- wscript | 11 +++++++++++ 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. */ typedef void* SLV2Plugins; /**< set. */ @@ -305,11 +315,12 @@ slv2_value_as_bool(SLV2Value value);
  • SLV2UIs (function prefix "slv2_uis_")
    • - Each collection type supports the following functions: + Each collection type supports a similar basic API:
      -
    • PREFIX_free (coll)
      • -
    • PREFIX_size (coll)
      • -
    • PREFIX_get_at (coll, index)
      • +
    • void PREFIX_free (coll)
      • +
    • unsigned PREFIX_size (coll)
      • +
    • SLV2Iter PREFIX_begin (coll)
      • +
    • ELEM PREFIX_get_at (coll, index) (DEPRECATED)
    @{ */ @@ -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). @@ -1145,6 +1162,10 @@ typedef struct _Instance { SLV2InstanceImpl pimpl; ///< Private implementation }* SLV2Instance; +/** + @endcond +*/ + /** Instantiate a plugin. The returned value is a lightweight handle for an LV2 plugin instance, @@ -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']) -- cgit v1.2.1