From aefb54c61703a6c0efe785945e1dd1db767de4f5 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Fri, 27 Nov 2009 17:40:15 +0000
Subject: Documentation updates.

git-svn-id: http://svn.drobilla.net/lad/trunk/raul@2286 a436a847-0d15-0410-975c-d299462d15a1
---
 raul/Atom.hpp   |  6 +++++-
 raul/Path.hpp   | 14 +++++++-------
 raul/Symbol.hpp | 11 ++++++++---
 3 files changed, 20 insertions(+), 11 deletions(-)

(limited to 'raul')

diff --git a/raul/Atom.hpp b/raul/Atom.hpp
index 4dc28e2..7581e46 100644
--- a/raul/Atom.hpp
+++ b/raul/Atom.hpp
@@ -31,7 +31,11 @@
 namespace Raul {
 
 
-/** An OSC atom (fundamental data types OSC messages are composed of).
+/** A piece of data with some type.
+ *
+ * Atoms can be of various primitive types (integer, float, etc) as well as
+ * a string or primitive.  The primitive types are entirely contained within
+ * the Atom, i.e. the Atom is POD.  String, URI, and blob atoms are not POD.
  *
  * \ingroup raul
  */
diff --git a/raul/Path.hpp b/raul/Path.hpp
index b549f88..5119530 100644
--- a/raul/Path.hpp
+++ b/raul/Path.hpp
@@ -30,17 +30,17 @@
 namespace Raul {
 
 
-/** Simple wrapper around standard string with useful path-specific methods.
+/** A URI which is a path (for example a filesystem or OSC path).
  *
- * This enforces that a Path is a valid OSC path (though it is used for
- * GraphObject paths, which aren't directly OSC paths but a portion of one).
+ * A Path always has the special URI scheme "path:".
+ *
+ * This enforces that a Path is a valid path, where each fragment is a valid
+ * Symbol, separated by exactly one slash (/).
  *
  * A path is divided by slashes (/).  The first character MUST be a slash, and
  * the last character MUST NOT be a slash (except in the special case of the
- * root path "/", which is the only valid single-character path).
- *
- * Valid characters are the 95 printable ASCII characters (32-126), excluding:
- * space # * , ? [ ] { }
+ * root path "/", which is the only valid single-character path).  The path:
+ * scheme is added automatically (since a Patch is actually a URI).
  *
  * \ingroup raul
  */
diff --git a/raul/Symbol.hpp b/raul/Symbol.hpp
index 6658cf3..8aa82c1 100644
--- a/raul/Symbol.hpp
+++ b/raul/Symbol.hpp
@@ -27,10 +27,15 @@
 namespace Raul {
 
 
-/** A restricted string (C identifier, which is a component of a path).
+/** A restricted string (C identifier, which is a component of a Path).
+ *
+ * A Symbol is a very restricted string suitable for use as an identifier.
+ * It is a valid LV2 symbol, URI fragment, filename, OSC path fragment,
+ * and identifier for most programming languages (including C).
+ *
+ * Valid characters are _, a-z, A-Z, 0-9, except the first character which
+ * must not be 0-9.
  *
- * A Symbol is an lv2-compliant symbol, which is also valid as a component of
- * a URI, filesystem or OSC path, programming language identifier, etc.
  * \ingroup raul
  */
 class Symbol : public std::basic_string<char> {
-- 
cgit v1.2.1