From 7cc90d01f3cd0c9fe620e8dec17e89a91d2d8345 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Thu, 7 Jan 2021 19:31:25 +0100
Subject: Clean up documentation comments

---
 include/raul/Symbol.hpp | 64 ++++++++++++++++++++++++++-----------------------
 1 file changed, 34 insertions(+), 30 deletions(-)

(limited to 'include/raul/Symbol.hpp')

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()) {
-- 
cgit v1.2.1