Documentation updates.

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

3 files changed, 20 insertions, 11 deletions

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> {