Clean up documentation comments

12 files changed, 216 insertions, 187 deletions

diff --git a/include/raul/Array.hpp b/include/raul/Array.hpp
index 10f352d..911fca9 100644
--- a/include/raul/Array.hpp
+++ b/include/raul/Array.hpp
@@ -25,10 +25,11 @@
 
 namespace raul {
 
-/** A disposable array with size.
- *
- * \ingroup raul
- */
+/**
+   A disposable array with a size.
+
+   @ingroup raul
+*/
 template<class T>
 class Array : public Maid::Disposable
 {
diff --git a/include/raul/Deletable.hpp b/include/raul/Deletable.hpp
index e8f33bc..704d89c 100644
--- a/include/raul/Deletable.hpp
+++ b/include/raul/Deletable.hpp
@@ -18,10 +18,11 @@
 
 namespace raul {
 
-/** Something with a virtual destructor.
- *
- * \ingroup raul
- */
+/**
+   Something with a virtual destructor.
+
+   @ingroup raul
+*/
 class Deletable
 {
 public:
diff --git a/include/raul/DoubleBuffer.hpp b/include/raul/DoubleBuffer.hpp
index 1693f25..ac5256d 100644
--- a/include/raul/DoubleBuffer.hpp
+++ b/include/raul/DoubleBuffer.hpp
@@ -21,16 +21,18 @@
 
 namespace raul {
 
-/** Double buffer.
- *
- * Can be thought of as a wrapper class to make a non-atomic type atomically
- * settable (with no locking).
- *
- * Read/Write realtime safe, many writers safe - but set calls may fail.
- *
- * Space:  2*sizeof(T) + sizeof(int) + sizeof(void*)
- * \ingroup raul
- */
+/**
+   Double buffer.
+
+   Can be thought of as a wrapper class to make a non-atomic type atomically
+   settable (with no locking).
+
+   Read/Write realtime safe, many writers safe - but set calls may fail.
+
+   Space:  2*sizeof(T) + sizeof(int) + sizeof(void*)
+
+   @ingroup raul
+*/
 template<typename T>
 class DoubleBuffer
 {
diff --git a/include/raul/Exception.hpp b/include/raul/Exception.hpp
index 595800f..13dea19 100644
--- a/include/raul/Exception.hpp
+++ b/include/raul/Exception.hpp
@@ -22,7 +22,11 @@
 
 namespace raul {
 
-/** An exception (unexpected error). */
+/**
+   An exception (unexpected error).
+
+   @ingroup raul
+*/
 class Exception : public std::exception
 {
 public:
diff --git a/include/raul/Maid.hpp b/include/raul/Maid.hpp
index bc0ac4f..5c02b7f 100644
--- a/include/raul/Maid.hpp
+++ b/include/raul/Maid.hpp
@@ -25,20 +25,21 @@
 
 namespace raul {
 
-/** Explicit garbage-collector.
- *
- * This allows objects to be disposed of in a real-time thread, but actually
- * deleted later by another thread which calls cleanup().  Disposable objects
- * may be explicitly disposed by calling dispose(), or automatically managed
- * with a managed_ptr which can safely be dropped in any thread, including
- * real-time threads.
- *
- * \ingroup raul
- */
+/**
+   Explicit garbage collector.
+
+   This allows objects to be disposed of in a real-time thread, but actually
+   deleted later by another thread which calls cleanup().  Disposable objects
+   may be explicitly disposed by calling dispose(), or automatically managed
+   with a managed_ptr which can safely be dropped in any thread, including
+   real-time threads.
+
+   @ingroup raul
+*/
 class Maid : public Noncopyable
 {
 public:
-  /** An object that can be disposed via Maid::dispose(). */
+  /// An object that can be disposed via Maid::dispose()
   class Disposable : public Deletable
   {
   public:
@@ -57,7 +58,7 @@ public:
     Disposable* _maid_next{};
   };
 
-  /** Disposable wrapper for any type. */
+  /// Disposable wrapper for any type
   template<typename T>
   class Managed
     : public raul::Maid::Disposable
@@ -70,7 +71,7 @@ public:
     {}
   };
 
-  /** Deleter for Disposable objects. */
+  /// Deleter for Disposable objects
   template<typename T>
   class Disposer
   {
@@ -92,11 +93,12 @@ public:
     Maid* _maid{nullptr};
   };
 
-  /** A managed pointer that automatically disposes of its contents.
-   *
-   * This is a unique_ptr so that it is possible to statically verify that
-   * code is real-time safe.
-   */
+  /**
+     A managed pointer that automatically disposes of its contents.
+
+     This is a unique_ptr so that it is possible to statically verify that
+     code is real-time safe.
+  */
   template<typename T>
   using managed_ptr = std::unique_ptr<T, Disposer<T>>;
 
@@ -112,17 +114,18 @@ public:
 
   inline ~Maid() { cleanup(); }
 
-  /** Return false iff there is currently no garbage. */
+  /// Return false iff there is currently no garbage
   inline bool empty() const
   {
     return !_disposed.load(std::memory_order_relaxed);
   }
 
-  /** Enqueue an object for deletion when cleanup() is called next.
-   *
-   * This is thread-safe, and real-time safe assuming reasonably low
-   * contention.
-   */
+  /**
+     Enqueue an object for deletion when cleanup() is called next.
+
+     This is thread-safe, and real-time safe assuming reasonably low
+     contention.
+  */
   inline void dispose(Disposable* obj)
   {
     if (obj) {
@@ -136,11 +139,12 @@ public:
     }
   }
 
-  /** Delete all disposed objects immediately.
-   *
-   * Obviously not real-time safe, but may be called while other threads are
-   * calling dispose().
-   */
+  /**
+     Delete all disposed objects immediately.
+
+     Obviously not real-time safe, but may be called while other threads are
+     calling dispose().
+  */
   inline void cleanup()
   {
     // Atomically get the head of the disposed list
@@ -155,7 +159,7 @@ public:
     }
   }
 
-  /** Make a unique_ptr that will dispose its object when dropped. */
+  /// Make a unique_ptr that will dispose its object when dropped
   template<class T, class... Args>
   managed_ptr<T> make_managed(Args&&... args)
   {
diff --git a/include/raul/Noncopyable.hpp b/include/raul/Noncopyable.hpp
index 189bd22..76e1f6d 100644
--- a/include/raul/Noncopyable.hpp
+++ b/include/raul/Noncopyable.hpp
@@ -18,10 +18,11 @@
 
 namespace raul {
 
-/** Convenience base for non-copyable and non-movable classes.
- *
- * \ingroup raul
- */
+/**
+   Convenience base for non-copyable and non-movable classes.
+
+   @ingroup raul
+*/
 class Noncopyable
 {
 public:
diff --git a/include/raul/Path.hpp b/include/raul/Path.hpp
index e5ca5c9..1ddfb24 100644
--- a/include/raul/Path.hpp
+++ b/include/raul/Path.hpp
@@ -25,17 +25,18 @@
 
 namespace raul {
 
-/** A restricted path of Symbols separated by, and beginning with, "/".
- *
- * A Path never ends with a "/", except for the root Path "/", which is the
- * only valid single-character Path.
- *
- * @ingroup raul
- */
+/**
+   A restricted path of Symbols separated by, and beginning with, "/".
+
+   A Path never ends with a "/", except for the root Path "/", which is the
+   only valid single-character Path.
+
+   @ingroup raul
+*/
 class Path : public std::basic_string<char>
 {
 public:
-  /** Attempt to construct an invalid Path. */
+  /// Attempt to construct an invalid Path
   class BadPath : public Exception
   {
   public:
@@ -44,16 +45,17 @@ public:
     {}
   };
 
-  /** Construct an uninitialzed path, because the STL is annoying. */
+  /// Construct the root path `/`
   Path()
     : std::basic_string<char>("/")
   {}
 
-  /** Construct a Path from a C++ string.
-   *
-   * This will throw an exception if `path` is invalid.  To avoid this, use
-   * is_valid() first to check.
-   */
+  /**
+     Construct a Path from a C++ string.
+
+     This will throw an exception if `path` is invalid.  To avoid this, use
+     is_valid() first to check.
+  */
   explicit Path(const std::basic_string<char>& path)
     : std::basic_string<char>(path)
   {
@@ -62,11 +64,12 @@ public:
     }
   }
 
-  /** Construct a Path from a C string.
-   *
-   * This will throw an exception if `path` is invalid.  To avoid this, use
-   * is_valid() first to check.
-   */
+  /**
+     Construct a Path from a C string.
+
+     This will throw an exception if `path` is invalid.  To avoid this, use
+     is_valid() first to check.
+  */
   explicit Path(const char* path)
     : std::basic_string<char>(path)
   {
@@ -83,13 +86,13 @@ public:
 
   ~Path() = default;
 
-  /** Return true iff `c` is a valid Path character. */
+  /// Return true iff `c` is a valid Path character
   static inline bool is_valid_char(char c)
   {
     return c == '/' || Symbol::is_valid_char(c);
   }
 
-  /** Return true iff `str` is a valid Path. */
+  /// Return true iff `str` is a valid Path
   static inline bool is_valid(const std::basic_string<char>& str)
   {
     if (str.empty() || (str[0] != '/')) {
@@ -119,28 +122,29 @@ public:
     return true;
   }
 
-  /** Return true iff this path is the root path ("/"). */
+  /// Return true iff this path is the root path ("/")
   inline bool is_root() const { return *this == "/"; }
 
-  /** Return true iff this path is a child of `parent` at any depth. */
+  /// Return true iff this path is a child of `parent` at any depth
   inline bool is_child_of(const Path& parent) const
   {
     const std::string parent_base = parent.base();
     return substr(0, parent_base.length()) == parent_base;
   }
 
-  /** Return true iff this path is a parent of `child` at any depth. */
+  /// Return true iff this path is a parent of `child` at any depth
   inline bool is_parent_of(const Path& child) const
   {
     return child.is_child_of(*this);
   }
 
-  /** Return the symbol of this path (everything after the last '/').
-   *
-   * This is what is called the "basename" for file paths, the "method name"
-   * for OSC paths, and so on.  Since the root path does not have a symbol,
-   * this does not return a raul::Symbol but may return the empty string.
-   */
+  /**
+     Return the symbol of this path (everything after the last '/').
+
+     This is what is called the "basename" for file paths, the "method name"
+     for OSC paths, and so on.  Since the root path does not have a symbol,
+     this does not return a raul::Symbol but may return the empty string.
+  */
   inline const char* symbol() const
   {
     if (!is_root()) {
@@ -152,11 +156,12 @@ public:
     return "";
   }
 
-  /** Return the parent's path.
-   *
-   * Calling this on the path "/" will return "/".
-   * This is the (deepest) "container path" for OSC paths.
-   */
+  /**
+     Return the parent's path.
+
+     Calling this on the path "/" will return "/".
+     This is the (deepest) "container path" for OSC paths.
+  */
   inline Path parent() const
   {
     if (is_root()) {
@@ -168,23 +173,24 @@ public:
     return (first_sep == last_sep) ? Path("/") : Path(substr(0, last_sep));
   }
 
-  /** Return a child Path of this path. */
+  /// Return a child Path of this path
   inline Path child(const Path& p) const
   {
     return p.is_root() ? *this : Path(base() + p.substr(1));
   }
 
-  /** Return a direct child Path of this Path with the given Symbol. */
+  /// Return a direct child Path of this Path with the given Symbol
   inline Path child(const raul::Symbol& symbol) const
   {
     return Path(base() + symbol.c_str());
   }
 
-  /** Return path with a trailing "/".
-   *
-   * The returned string is such that appending a valid Symbol to it is
-   * guaranteed to form a valid path.
-   */
+  /**
+     Return path with a trailing "/".
+
+     The returned string is such that appending a valid Symbol to it is
+     guaranteed to form a valid path.
+  */
   inline std::string base() const
   {
     if (is_root()) {
@@ -194,7 +200,7 @@ public:
     return *this + '/';
   }
 
-  /** Return the lowest common ancestor of a and b. */
+  /// Return the lowest common ancestor of a and b
   static inline Path lca(const Path& a, const Path& b)
   {
     const size_t len      = std::min(a.length(), b.length());
@@ -215,7 +221,7 @@ public:
     return Path(a.substr(0, last_sep));
   }
 
-  /** Return true iff `child` is equal to, or a descendant of `parent`. */
+  /// Return true iff `child` is equal to, or a descendant of `parent`
   static inline bool descendant_comparator(const Path& parent,
                                            const Path& child)
   {
diff --git a/include/raul/Process.hpp b/include/raul/Process.hpp
index b05b038..085ed8b 100644
--- a/include/raul/Process.hpp
+++ b/include/raul/Process.hpp
@@ -23,18 +23,20 @@
 
 namespace raul {
 
-/** A child process.
- *
- * \ingroup raul
- */
+/**
+   A child process.
+
+   @ingroup raul
+*/
 class Process : Noncopyable
 {
 public:
-  /** Launch a sub process.
-   *
-   * @param argv List of arguments, where argv[0] is the command name.
-   * @return True on success.
-   */
+  /**
+     Launch a sub process.
+
+     @param argv List of arguments, where argv[0] is the command name.
+     @return True on success.
+  */
   static bool launch(const char* const argv[])
   {
     // Use the same double fork() trick as JACK to prevent zombie children
diff --git a/include/raul/RingBuffer.hpp b/include/raul/RingBuffer.hpp
index d194ca4..9c49d1b 100644
--- a/include/raul/RingBuffer.hpp
+++ b/include/raul/RingBuffer.hpp
@@ -39,8 +39,9 @@ class RingBuffer : public Noncopyable
 public:
   /**
      Create a new RingBuffer.
+
      @param size Size in bytes (note this may be rounded up).
-   */
+  */
   explicit RingBuffer(uint32_t size)
     : _write_head(0)
     , _read_head(0)
@@ -72,38 +73,28 @@ public:
     _read_head  = 0;
   }
 
-  /**
-     Return the number of bytes of space available for reading.
-  */
+  /// Return the number of bytes of space available for reading
   inline uint32_t read_space() const
   {
     return read_space_internal(_read_head, _write_head);
   }
 
-  /**
-     Return the number of bytes of space available for writing.
-  */
+  /// Return the number of bytes of space available for writing
   inline uint32_t write_space() const
   {
     return write_space_internal(_read_head, _write_head);
   }
 
-  /**
-     Return the capacity (i.e. total write space when empty).
-  */
+  /// Return the capacity (i.e. total write space when empty)
   inline uint32_t capacity() const { return _size - 1; }
 
-  /**
-     Read from the RingBuffer without advancing the read head.
-  */
+  /// Read from the RingBuffer without advancing the read head
   inline uint32_t peek(uint32_t size, void* dst)
   {
     return peek_internal(_read_head, _write_head, size, dst);
   }
 
-  /**
-     Read from the RingBuffer and advance the read head.
-  */
+  /// Read from the RingBuffer and advance the read head
   inline uint32_t read(uint32_t size, void* dst)
   {
     const uint32_t r = _read_head;
@@ -118,9 +109,7 @@ public:
     return 0;
   }
 
-  /**
-     Skip data in the RingBuffer (advance read head without reading).
-  */
+  /// Skip data in the RingBuffer (advance read head without reading)
   inline uint32_t skip(uint32_t size)
   {
     const uint32_t r = _read_head;
@@ -134,9 +123,7 @@ public:
     return size;
   }
 
-  /**
-     Write data to the RingBuffer.
-  */
+  /// Write data to the RingBuffer
   inline uint32_t write(uint32_t size, const void* src)
   {
     const uint32_t r = _read_head;
diff --git a/include/raul/Semaphore.hpp b/include/raul/Semaphore.hpp
index 9e8dbb1..f4dc447 100644
--- a/include/raul/Semaphore.hpp
+++ b/include/raul/Semaphore.hpp
@@ -43,6 +43,8 @@ namespace raul {
    At least on Lignux, the main advantage of this is that it is fast and the
    only safe way to reliably signal from a real-time audio thread.  The
    counting semantics also complement ringbuffers of events nicely.
+
+   @ingroup raul
 */
 class Semaphore
 {
@@ -68,23 +70,23 @@ public:
 
   inline ~Semaphore() { destroy(); }
 
-  /** Destroy and reset to a new initial value. */
+  /// Destroy and reset to a new initial value
   inline void reset(unsigned initial)
   {
     destroy();
     init(initial);
   }
 
-  /** Post/Increment/Signal */
+  /// Post/Increment/Signal
   inline void post();
 
-  /** Wait/Decrement.  Return false on error. */
+  /// Wait/Decrement, return false on error
   inline bool wait();
 
-  /** Attempt Wait/Decrement.  Return true iff decremented. */
+  /// Attempt Wait/Decrement, return true iff decremented
   inline bool try_wait();
 
-  /** Wait for at most `ms` milliseconds.  Return true iff decremented. */
+  /// Wait for at most `ms` milliseconds, return true iff decremented
   template<class Rep, class Period>
   inline bool timed_wait(const std::chrono::duration<Rep, Period>& wait);
 
diff --git a/include/raul/Socket.hpp b/include/raul/Socket.hpp
index 55d2f70..6a2883c 100644
--- a/include/raul/Socket.hpp
+++ b/include/raul/Socket.hpp
@@ -31,16 +31,20 @@
 
 namespace raul {
 
-/** A safe and simple interface for UNIX or TCP sockets. */
+/**
+   A safe and simple interface for UNIX or TCP sockets.
+
+   @ingroup raul
+*/
 class Socket : public raul::Noncopyable
 {
 public:
   enum class Type { UNIX, TCP };
 
-  /** Create a new unbound/unconnected socket of a given type. */
+  /// Create a new unbound/unconnected socket of a given type
   explicit Socket(Type t);
 
-  /** Wrap an existing open socket. */
+  /// Wrap an existing open socket
   Socket(Type             t,
          std::string      uri,
          struct sockaddr* addr,
@@ -55,41 +59,52 @@ public:
 
   ~Socket();
 
-  /** Bind a server socket to an address.
-   * @param uri Address URI, e.g. unix:///tmp/foo, or tcp://hostname:1234.
-   *            Use "*" as hostname to listen on all interfaces.
-   * @return True on success.
-   */
+  /**
+     Bind a server socket to an address.
+
+     @param uri Address URI, e.g. unix:///tmp/foo, or tcp://hostname:1234.
+     Use "*" as hostname to listen on all interfaces.
+
+     @return True on success.
+  */
   bool bind(const std::string& uri);
 
-  /** Connect a client socket to a server address.
-   * @param uri Address URI, e.g. unix:///tmp/foo or tcp://somehost:1234
-   * @return True on success.
-   */
+  /**
+     Connect a client socket to a server address.
+
+     @param uri Address URI, e.g. unix:///tmp/foo or tcp://somehost:1234
+     @return True on success.
+  */
   bool connect(const std::string& uri);
 
-  /** Mark server socket as passive to listen for incoming connections.
-   * @return True on success.
-   */
+  /**
+     Mark server socket as passive to listen for incoming connections.
+
+     @return True on success.
+  */
   bool listen();
 
-  /** Accept a connection.
-   * @return An new open socket for the connection.
-   */
+  /**
+     Accept a connection.
+
+     @return An new open socket for the connection.
+  */
   std::shared_ptr<Socket> accept();
 
-  /** Return the file descriptor for the socket. */
+  /// Return the file descriptor for the socket
   int fd() const { return _sock; }
 
   const std::string& uri() const { return _uri; }
 
-  /** Close the socket. */
+  /// Close the socket
   void close();
 
-  /** Shut down the socket.
-   * This terminates any connections associated with the sockets, and will
-   * (unlike close()) cause a poll on the socket to return.
-   */
+  /**
+     Shut down the socket.
+
+     This terminates any connections associated with the socket, and will
+     (unlike close()) cause a poll on the socket to return.
+  */
   void shutdown();
 
 private:
diff --git a/include/raul/Symbol.hpp b/include/raul/Symbol.hpp
index 10446d0..a4ac6bd 100644
--- a/include/raul/Symbol.hpp
+++ b/include/raul/Symbol.hpp
@@ -24,21 +24,22 @@
 
 namespace raul {
 
-/** A restricted string which is a valid C identifier and Path component.
- *
- * 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 virtually all programming languages.
- *
- * Valid characters are _, a-z, A-Z, 0-9, except the first character which
- * must not be 0-9.
- *
- * @ingroup raul
- */
+/**
+   A restricted string which is a valid C identifier and Path component.
+
+   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 virtually all programming languages.
+
+   Valid characters are _, a-z, A-Z, 0-9, except the first character which
+   must not be 0-9.
+
+   @ingroup raul
+*/
 class Symbol : public std::basic_string<char>
 {
 public:
-  /** Attempt to construct an invalid Symbol. */
+  /// Attempt to construct an invalid Symbol
   class BadSymbol : public Exception
   {
   public:
@@ -47,11 +48,12 @@ public:
     {}
   };
 
-  /** Construct a Symbol from a C++ string.
-   *
-   * This will throw an exception if `symbol` is invalid.  To avoid this,
-   * use is_valid() first to check.
-   */
+  /**
+     Construct a Symbol from a C++ string.
+
+     This will throw an exception if `symbol` is invalid.  To avoid this,
+     use is_valid() first to check.
+  */
   explicit Symbol(const std::basic_string<char>& symbol)
     : std::basic_string<char>(symbol)
   {
@@ -60,11 +62,12 @@ public:
     }
   }
 
-  /** Construct a Symbol from a C string.
-   *
-   * This will throw an exception if `symbol` is invalid.  To avoid this,
-   * use is_valid() first to check.
-   */
+  /**
+     Construct a Symbol from a C string.
+
+     This will throw an exception if `symbol` is invalid.  To avoid this,
+     use is_valid() first to check.
+  */
   explicit Symbol(const char* symbol)
     : std::basic_string<char>(symbol)
   {
@@ -81,19 +84,19 @@ public:
 
   ~Symbol() = default;
 
-  /** Return true iff `c` is a valid Symbol start character. */
+  /// Return true iff `c` is a valid Symbol start character
   static inline bool is_valid_start_char(char c)
   {
     return (c == '_') || (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
   }
 
-  /** Return true iff `c` is a valid Symbol character. */
+  /// Return true iff `c` is a valid Symbol character
   static inline bool is_valid_char(char c)
   {
     return is_valid_start_char(c) || (c >= '0' && c <= '9');
   }
 
-  /** Return true iff `str` is a valid Symbol. */
+  /// Return true iff `str` is a valid Symbol
   static inline bool is_valid(const std::basic_string<char>& str)
   {
     if (str.empty() || (str[0] >= '0' && str[0] <= '9')) {
@@ -103,11 +106,12 @@ public:
     return std::all_of(str.begin(), str.end(), is_valid_char);
   }
 
-  /** Convert a string to a valid symbol.
-   *
-   * This will make a best effort at turning `str` into a complete, valid
-   * Symbol, and will always return one.
-   */
+  /**
+     Convert a string to a valid symbol.
+
+     This will make a best effort at turning `str` into a complete, valid
+     Symbol, and will always return one.
+  */
   static inline Symbol symbolify(const std::basic_string<char>& in)
   {
     if (in.empty()) {