Tidy up documentation, remove cruft.

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

1 files changed, 25 insertions, 61 deletions

diff --git a/slv2/value.h b/slv2/value.h
index 84c5b94..8e68718 100644
--- a/slv2/value.h
+++ b/slv2/value.h
@@ -24,14 +24,14 @@ extern "C" {
 #endif
 
 #include <stdbool.h>
+
 #include "slv2/types.h"
 
-/** \addtogroup slv2_data
+/** @addtogroup slv2_data
  * @{
  */
 
 /** Create a new URI value.
- *
  * Returned value must be freed by caller with slv2_value_free.
  */
 SLV2_API
@@ -39,7 +39,6 @@ SLV2Value
 slv2_value_new_uri(SLV2World world, const char* uri);
 
 /** Create a new string value (with no language).
- *
  * Returned value must be freed by caller with slv2_value_free.
  */
 SLV2_API
@@ -47,7 +46,6 @@ SLV2Value
 slv2_value_new_string(SLV2World world, const char* str);
 
 /** Create a new integer value.
- *
  * Returned value must be freed by caller with slv2_value_free.
  */
 SLV2_API
@@ -55,7 +53,6 @@ SLV2Value
 slv2_value_new_int(SLV2World world, int val);
 
 /** Create a new floating point value.
- *
  * Returned value must be freed by caller with slv2_value_free.
  */
 SLV2_API
@@ -63,7 +60,6 @@ SLV2Value
 slv2_value_new_float(SLV2World world, float val);
 
 /** Create a new boolean value.
- *
  * Returned value must be freed by caller with slv2_value_free.
  */
 SLV2_API
@@ -89,135 +85,103 @@ bool
 slv2_value_equals(SLV2Value value, SLV2Value other);
 
 /** Return this value as a Turtle/SPARQL token.
- * Examples:
- *   <http://example.org/foo>
- *   doap:name
- *   "this is a string"
- *   1.0
- *   1
- *
- * Returned string is newly allocated and must be freed by caller.
+ * <table>
+ * <caption>Example Turtle Tokens</caption>
+ * <tr><th>URI</th><td>&lt;http://example.org/foo &gt;</td></tr>
+ * <tr><th>QName</td><td>doap:name</td></tr>
+ * <tr><th>String</td><td>"this is a string"</td></tr>
+ * <tr><th>Float</td><td>1.0</td></tr>
+ * <tr><th>Integer</td><td>1</td></tr>
+ * <tr><th>Boolean</td><td>true</td></tr>
+ * </table>
  */
 SLV2_API
 char*
 slv2_value_get_turtle_token(SLV2Value value);
 
 /** Return whether the value is a URI (resource).
- *
- * Time = O(1)
  */
 SLV2_API
 bool
 slv2_value_is_uri(SLV2Value value);
 
 /** Return this value as a URI string, e.g. "http://example.org/foo".
- *
- * Valid to call only if slv2_value_is_uri(\a value) returns true.
- * Returned value is owned by \a value and must not be freed by caller.
- *
- * Time = O(1)
+ * Valid to call only if slv2_value_is_uri(@a value) returns true.
+ * Returned value is owned by @a value and must not be freed by caller.
  */
 SLV2_API
 const char*
 slv2_value_as_uri(SLV2Value value);
 
 /** Return whether the value is a blank node (resource with no URI).
- *
- * Time = O(1)
  */
 SLV2_API
 bool
 slv2_value_is_blank(SLV2Value value);
 
 /** Return this value as a blank node identifier, e.g. "genid03".
- *
- * Valid to call only if slv2_value_is_blank(\a value) returns true.
- * Returned value is owned by \a value and must not be freed by caller.
- *
- * Time = O(1)
+ * Valid to call only if slv2_value_is_blank(@a value) returns true.
+ * Returned value is owned by @a value and must not be freed by caller.
  */
 SLV2_API
 const char*
 slv2_value_as_blank(SLV2Value value);
 
 /** Return whether this value is a literal (i.e. not a URI).
- *
- * Returns true if \a value is a string or numeric value.
- *
- * Time = O(1)
+ * Returns true if @a value is a string or numeric value.
  */
 SLV2_API
 bool
 slv2_value_is_literal(SLV2Value value);
 
 /** Return whether this value is a string literal.
- *
- * Returns true if \a value is a string (but not  numeric) value.
- *
- * Time = O(1)
+ * Returns true if @a value is a string (but not  numeric) value.
  */
 SLV2_API
 bool
 slv2_value_is_string(SLV2Value value);
 
-/** Return \a value as a string.
- *
- * Time = O(1)
+/** Return @a value as a string.
  */
 SLV2_API
 const char*
 slv2_value_as_string(SLV2Value value);
 
 /** Return whether this value is a decimal literal.
- *
- * Time = O(1)
  */
 SLV2_API
 bool
 slv2_value_is_float(SLV2Value value);
 
-/** Return \a value as a float.
- *
- * Valid to call only if slv2_value_is_float(\a value) or
- * slv2_value_is_int(\a value) returns true.
- *
- * Time = O(1)
+/** Return @a value as a float.
+ * Valid to call only if slv2_value_is_float(@a value) or
+ * slv2_value_is_int(@a value) returns true.
  */
 SLV2_API
 float
 slv2_value_as_float(SLV2Value value);
 
 /** Return whether this value is an integer literal.
- *
- * Time = O(1)
  */
 SLV2_API
 bool
 slv2_value_is_int(SLV2Value value);
 
-/** Return \a value as an integer.
- *
- * Valid to call only if slv2_value_is_int(\a value) returns true.
- *
- * Time = O(1)
+/** Return @a value as an integer.
+ * Valid to call only if slv2_value_is_int(@a value) returns true.
  */
 SLV2_API
 int
 slv2_value_as_int(SLV2Value value);
 
 /** Return whether this value is a boolean.
- *
- * Time = O(1)
  */
 SLV2_API
 bool
 slv2_value_is_bool(SLV2Value value);
 
-/** Return \a value as a bool.
- *
- * Valid to call only if slv2_value_is_bool(\a value) returns true.
- *
- * Time = O(1)
+/** Return @a value as a bool.
+ * Valid to call only if slv2_value_is_bool(@a value) returns true.
  */
 SLV2_API
 bool