[5114] Doxygen escapes fixed.

src/lib/cc/data.h

@@ -23,7 +23,7 @@ typedef boost::shared_ptr<Element> ElementPtr;
 typedef boost::shared_ptr<const Element> ConstElementPtr;
 
 ///
-/// \brief A standard Data module exception that is thrown if a function
+/// @brief A standard Data module exception that is thrown if a function
 /// is called for an Element that has a wrong type (e.g. int_value on a
 /// ListElement)
 ///
@@ -34,7 +34,7 @@ public:
 };
 
 ///
-/// \brief A standard Data module exception that is thrown if a parse
+/// @brief A standard Data module exception that is thrown if a parse
 /// error is encountered when constructing an Element from a string
 ///
 // i'd like to use Exception here but we need one that is derived from
@@ -47,32 +47,32 @@ public:
 };
 
 ///
-/// \brief The \c Element class represents a piece of data, used by
+/// @brief The @c Element class represents a piece of data, used by
 /// the command channel and configuration parts.
 ///
-/// An \c Element can contain simple types (int, real, string, bool and
+/// An @c Element can contain simple types (int, real, string, bool and
 /// None), and composite types (list and string->element maps)
 ///
 /// Elements should in calling functions usually be referenced through
-/// an \c ElementPtr, which can be created using the factory functions
-/// \c Element::create() and \c Element::fromJSON()
+/// an @c ElementPtr, which can be created using the factory functions
+/// @c Element::create() and @c Element::fromJSON()
 ///
 /// Notes to developers: Element is a base class, implemented by a
 /// specific subclass for each type (IntElement, BoolElement, etc).
 /// Element does define all functions for all types, and defaults to
-/// raising a \c TypeError for functions that are not supported for
+/// raising a @c TypeError for functions that are not supported for
 /// the type in question.
 ///
 class Element {
 
 public:
-    /// \brief Represents the position of the data element within a
+    /// @brief Represents the position of the data element within a
     /// configuration string.
     ///
     /// Position comprises a file name, line number and an offset within this
     /// line where the element value starts. For example, if the JSON string is
     ///
-    /// \code
+    /// @code
     /// { "foo": "some string",
     ///   "bar": 123 }
     /// \endcode
@@ -90,27 +90,27 @@ public:
         uint32_t line_;    ///< Line number.
         uint32_t pos_;     ///< Position within the line.
 
-        /// \brief Default constructor.
+        /// @brief Default constructor.
         Position() : file_(""), line_(0), pos_(0) {
         }
 
-        /// \brief Constructor.
+        /// @brief Constructor.
         ///
-        /// \param file File name.
-        /// \param line Line number.
-        /// \param pos Position within the line.
+        /// @param file File name.
+        /// @param line Line number.
+        /// @param pos Position within the line.
         Position(const std::string& file, const uint32_t line,
                  const uint32_t pos)
             : file_(file), line_(line), pos_(pos) {
         }
 
-        /// \brief Returns the position in the textual format.
+        /// @brief Returns the position in the textual format.
         ///
         /// The returned position has the following format: file:line:pos.
         std::string str() const;
     };
 
-    /// \brief Returns @c Position object with line_ and pos_ set to 0, and
+    /// @brief Returns @c Position object with line_ and pos_ set to 0, and
     /// with an empty file name.
     ///
     /// The object containing two zeros is a default for most of the
@@ -128,15 +128,15 @@ private:
     // function getType?
     int type_;
 
-    /// \brief Position of the element in the configuration string.
+    /// @brief Position of the element in the configuration string.
     Position position_;
 
 protected:
 
-    /// \brief Constructor.
+    /// @brief Constructor.
     ///
-    /// \param t Element type.
-    /// \param pos Structure holding position of the value of the data element.
+    /// @param t Element type.
+    /// @param pos Structure holding position of the value of the data element.
     /// It comprises the line number and the position within this line. The values
     /// held in this structure are used for error logging purposes.
     Element(int t, const Position& pos = ZERO_POSITION())
@@ -152,10 +152,10 @@ public:
     // base class; make dtor virtual
     virtual ~Element() {};
 
-    /// \return the type of this element
+    /// @return the type of this element
     int getType() const { return (type_); }
 
-    /// \brief Returns position where the data element's value starts in a
+    /// @brief Returns position where the data element's value starts in a
     /// configuration string.
     ///
     /// @warning The returned reference is valid as long as the object which
@@ -168,17 +168,17 @@ public:
     ///
     /// The resulting string will contain the Element in JSON format.
     ///
-    /// \return std::string containing the string representation
+    /// @return std::string containing the string representation
     std::string str() const;
 
     /// Returns the wireformat for the Element and all its child
     /// elements.
     ///
-    /// \return std::string containing the element in wire format
+    /// @return std::string containing the element in wire format
     std::string toWire() const;
     void toWire(std::ostream& out) const;
 
-    /// \brief Add the position to a TypeError message
+    /// @brief Add the position to a TypeError message
     /// should be used in place of isc_throw(TypeError, error)
 #define throwTypeError(error)                   \
     {                                           \
@@ -191,18 +191,18 @@ public:
         isc_throw(TypeError, msg_);             \
     }
 
-    /// \name pure virtuals, every derived class must implement these
+    /// @name pure virtuals, every derived class must implement these
 
-    /// \return true if the other ElementPtr has the same type and value
+    /// @return true if the other ElementPtr has the same type and value
     virtual bool equals(const Element& other) const = 0;
 
     /// Converts the Element to JSON format and appends it to
     /// the given stringstream.
     virtual void toJSON(std::ostream& ss) const = 0;
 
-    /// \name Type-specific getters
+    /// @name Type-specific getters
     ///
-    /// \brief These functions only
+    /// @brief These functions only
     /// work on their corresponding Element type. For all other
     /// types, a TypeError is thrown.
     /// If you want an exception-safe getter method, use
@@ -226,9 +226,9 @@ public:
     };
     //@}
 
-    /// \name Exception-safe getters
+    /// @name Exception-safe getters
     ///
-    /// \brief The getValue() functions return false if the given reference
+    /// @brief The getValue() functions return false if the given reference
     /// is of another type than the element contains
     /// By default it always returns false; the derived classes
     /// override the function for their type, copying their
@@ -244,9 +244,9 @@ public:
     //@}
 
     ///
-    /// \name Exception-safe setters.
+    /// @name Exception-safe setters.
     ///
-    /// \brief Return false if the Element is not
+    /// @brief Return false if the Element is not
     /// the right type. Set the value and return true if the Elements
     /// is of the correct type
     ///
@@ -267,35 +267,35 @@ public:
 
     // Other functions for specific subtypes
 
-    /// \name ListElement functions
+    /// @name ListElement functions
     ///
-    /// \brief If the Element on which these functions are called are not
+    /// @brief If the Element on which these functions are called are not
     /// an instance of ListElement, a TypeError exception is thrown.
     //@{
     /// Returns the ElementPtr at the given index. If the index is out
     /// of bounds, this function throws an std::out_of_range exception.
-    /// \param i The position of the ElementPtr to return
+    /// @param i The position of the ElementPtr to return
     virtual ConstElementPtr get(const int i) const;
 
-    /// \brief returns element as non-const pointer
+    /// @brief returns element as non-const pointer
     ///
-    /// \param i The position of the ElementPtr to retrieve
-    /// \return specified element pointer
+    /// @param i The position of the ElementPtr to retrieve
+    /// @return specified element pointer
     virtual ElementPtr getNonConst(const int i) const;
 
     /// Sets the ElementPtr at the given index. If the index is out
     /// of bounds, this function throws an std::out_of_range exception.
-    /// \param i The position of the ElementPtr to set
-    /// \param element The ElementPtr to set at the position
+    /// @param i The position of the ElementPtr to set
+    /// @param element The ElementPtr to set at the position
     virtual void set(const size_t i, ElementPtr element);
 
     /// Adds an ElementPtr to the list
-    /// \param element The ElementPtr to add
+    /// @param element The ElementPtr to add
     virtual void add(ElementPtr element);
 
     /// Removes the element at the given position. If the index is out
     /// of nothing happens.
-    /// \param i The index of the element to remove.
+    /// @param i The index of the element to remove.
     virtual void remove(const int i);
 
     /// Returns the number of elements in the list.
@@ -306,28 +306,28 @@ public:
     //@}
 
 
-    /// \name MapElement functions
+    /// @name MapElement functions
     ///
-    /// \brief If the Element on which these functions are called are not
+    /// @brief If the Element on which these functions are called are not
     /// an instance of MapElement, a TypeError exception is thrown.
     //@{
     /// Returns the ElementPtr at the given key
-    /// \param name The key of the Element to return
-    /// \return The ElementPtr at the given key, or null if not present
+    /// @param name The key of the Element to return
+    /// @return The ElementPtr at the given key, or null if not present
     virtual ConstElementPtr get(const std::string& name) const;
 
     /// Sets the ElementPtr at the given key
-    /// \param name The key of the Element to set
-    /// \param element The ElementPtr to set at the given key.
+    /// @param name The key of the Element to set
+    /// @param element The ElementPtr to set at the given key.
     virtual void set(const std::string& name, ConstElementPtr element);
 
     /// Remove the ElementPtr at the given key
-    /// \param name The key of the Element to remove
+    /// @param name The key of the Element to remove
     virtual void remove(const std::string& name);
 
     /// Checks if there is data at the given key
-    /// \param name The key of the Element to remove
-    /// \return true if there is data at the key, false if not.
+    /// @param name The key of the Element to remove
+    /// @return true if there is data at the key, false if not.
     virtual bool contains(const std::string& name) const;
 
     /// Recursively finds any data at the given identifier. The
@@ -339,30 +339,30 @@ public:
     /// Another Element at key "bar", the identifier for that last
     /// element from the first is "foo/bar".
     ///
-    /// \param identifier The identifier of the element to find
-    /// \return The ElementPtr at the given identifier. Returns a
+    /// @param identifier The identifier of the element to find
+    /// @return The ElementPtr at the given identifier. Returns a
     /// null ElementPtr if it is not found, which can be checked with
     /// Element::is_null(ElementPtr e).
     virtual ConstElementPtr find(const std::string& identifier) const;
 
-    /// See \c Element::find()
-    /// \param identifier The identifier of the element to find
-    /// \param t Reference to store the resulting ElementPtr, if found.
-    /// \return true if the element was found, false if not.
+    /// See @c Element::find()
+    /// @param identifier The identifier of the element to find
+    /// @param t Reference to store the resulting ElementPtr, if found.
+    /// @return true if the element was found, false if not.
     virtual bool find(const std::string& identifier, ConstElementPtr& t) const;
     //@}
 
 
-    /// \name Factory functions
+    /// @name Factory functions
 
     // TODO: should we move all factory functions to a different class
     // so as not to burden the Element base with too many functions?
     // and/or perhaps even to a separate header?
 
-    /// \name Direct factory functions
-    /// \brief These functions simply wrap the given data directly
+    /// @name Direct factory functions
+    /// @brief These functions simply wrap the given data directly
     /// in an Element object, and return a reference to it, in the form
-    /// of an \c ElementPtr.
+    /// of an @c ElementPtr.
     /// These factory functions are exception-free (unless there is
     /// no memory available, in which case bad_alloc is raised by the
     /// underlying system).
@@ -390,42 +390,42 @@ public:
     static ElementPtr create(const char *s,
                              const Position& pos = ZERO_POSITION());
 
-    /// \brief Creates an empty ListElement type ElementPtr.
+    /// @brief Creates an empty ListElement type ElementPtr.
     ///
-    /// \param pos A structure holding position of the data element value
+    /// @param pos A structure holding position of the data element value
     /// in the configuration string. It is used for error logging purposes.
     static ElementPtr createList(const Position& pos = ZERO_POSITION());
 
-    /// \brief Creates an empty MapElement type ElementPtr.
+    /// @brief Creates an empty MapElement type ElementPtr.
     ///
-    /// \param pos A structure holding position of the data element value
+    /// @param pos A structure holding position of the data element value
     /// in the configuration string. It is used for error logging purposes.
     static ElementPtr createMap(const Position& pos = ZERO_POSITION());
     //@}
 
 
-    /// \name Compound factory functions
+    /// @name Compound factory functions
 
-    /// \brief These functions will parse the given string (JSON)
+    /// @brief These functions will parse the given string (JSON)
     /// representation  of a compound element. If there is a parse
     /// error, an exception of the type isc::data::JSONError is thrown.
 
     //@{
     /// Creates an Element from the given JSON string
-    /// \param in The string to parse the element from
-    /// \param preproc specified whether preprocessing (e.g. comment removal)
+    /// @param in The string to parse the element from
+    /// @param preproc specified whether preprocessing (e.g. comment removal)
     ///                should be performed
-    /// \return An ElementPtr that contains the element(s) specified
+    /// @return An ElementPtr that contains the element(s) specified
     /// in the given string.
     static ElementPtr fromJSON(const std::string& in, bool preproc = false);
 
     /// Creates an Element from the given input stream containing JSON
     /// formatted data.
     ///
-    /// \param in The string to parse the element from
-    /// \param preproc specified whether preprocessing (e.g. comment removal)
+    /// @param in The string to parse the element from
+    /// @param preproc specified whether preprocessing (e.g. comment removal)
     ///                should be performed
-    /// \return An ElementPtr that contains the element(s) specified
+    /// @return An ElementPtr that contains the element(s) specified
     /// in the given input stream.
     static ElementPtr fromJSON(std::istream& in, bool preproc = false)
         throw(JSONError);
@@ -433,11 +433,11 @@ public:
     /// Creates an Element from the given input stream containing JSON
     /// formatted data.
     ///
-    /// \param in The string to parse the element from
-    /// \param file_name specified input file name (used in error reporting)
-    /// \param preproc specified whether preprocessing (e.g. comment removal)
+    /// @param in The string to parse the element from
+    /// @param file_name specified input file name (used in error reporting)
+    /// @param preproc specified whether preprocessing (e.g. comment removal)
     ///                should be performed
-    /// \return An ElementPtr that contains the element(s) specified
+    /// @return An ElementPtr that contains the element(s) specified
     /// in the given input stream.
     static ElementPtr fromJSON(std::istream& in, const std::string& file_name,
                                bool preproc = false)
@@ -446,13 +446,13 @@ public:
     /// Creates an Element from the given input stream, where we keep
     /// track of the location in the stream for error reporting.
     ///
-    /// \param in The string to parse the element from.
-    /// \param file The input file name.
-    /// \param line A reference to the int where the function keeps
+    /// @param in The string to parse the element from.
+    /// @param file The input file name.
+    /// @param line A reference to the int where the function keeps
     /// track of the current line.
-    /// \param pos A reference to the int where the function keeps
+    /// @param pos A reference to the int where the function keeps
     /// track of the current position within the current line.
-    /// \return An ElementPtr that contains the element(s) specified
+    /// @return An ElementPtr that contains the element(s) specified
     /// in the given input stream.
     // make this one private?
     static ElementPtr fromJSON(std::istream& in, const std::string& file,
@@ -470,23 +470,23 @@ public:
                                    bool preproc = false);
     //@}
 
-    /// \name Type name conversion functions
+    /// @name Type name conversion functions
 
     /// Returns the name of the given type as a string
     ///
-    /// \param type The type to return the name of
-    /// \return The name of the type, or "unknown" if the type
+    /// @param type The type to return the name of
+    /// @return The name of the type, or "unknown" if the type
     ///         is not known.
     static std::string typeToName(Element::types type);
 
     /// Converts the string to the corresponding type
     /// Throws a TypeError if the name is unknown.
     ///
-    /// \param type_name The name to get the type of
-    /// \return the corresponding type value
+    /// @param type_name The name to get the type of
+    /// @return the corresponding type value
     static Element::types nameToType(const std::string& type_name);
 
-    /// \brief input text preprocessor
+    /// @brief input text preprocessor
     ///
     /// This method performs preprocessing of the input stream (which is
     /// expected to contain a text version of to be parsed JSON). For now the
@@ -502,7 +502,7 @@ public:
     /// @param out output stream (filtered content will be written here)
     static void preprocess(std::istream& in, std::stringstream& out);
 
-    /// \name Wire format factory functions
+    /// @name Wire format factory functions
 
     /// These function pparse the wireformat at the given stringstream
     /// (of the given length). If there is a parse error an exception
@@ -514,17 +514,17 @@ public:
     /// Since the wire format is JSON, this is the same as
     /// fromJSON, and could be removed.
     ///
-    /// \param in The input stringstream.
-    /// \param length The length of the wireformat data in the stream
-    /// \return ElementPtr with the data that is parsed.
+    /// @param in The input stringstream.
+    /// @param length The length of the wireformat data in the stream
+    /// @return ElementPtr with the data that is parsed.
     static ElementPtr fromWire(std::stringstream& in, int length);
 
     /// Creates an Element from the wire format in the given string
     /// Since the wire format is JSON, this is the same as
     /// fromJSON, and could be removed.
     ///
-    /// \param s The input string
-    /// \return ElementPtr with the data that is parsed.
+    /// @param s The input string
+    /// @return ElementPtr with the data that is parsed.
     static ElementPtr fromWire(const std::string& s);
     //@}
 };
@@ -698,12 +698,12 @@ public:
 };
 
 /// Checks whether the given ElementPtr is a NULL pointer
-/// \param p The ElementPtr to check
-/// \return true if it is NULL, false if not.
+/// @param p The ElementPtr to check
+/// @return true if it is NULL, false if not.
 bool isNull(ConstElementPtr p);
 
 ///
-/// \brief Remove all values from the first ElementPtr that are
+/// @brief Remove all values from the first ElementPtr that are
 /// equal in the second. Both ElementPtrs MUST be MapElements
 /// The use for this function is to end up with a MapElement that
 /// only contains new and changed values (for ModuleCCSession and
@@ -711,14 +711,14 @@ bool isNull(ConstElementPtr p);
 /// Raises a TypeError if a or b are not MapElements
 void removeIdentical(ElementPtr a, ConstElementPtr b);
 
-/// \brief Create a new ElementPtr from the first ElementPtr, removing all
+/// @brief Create a new ElementPtr from the first ElementPtr, removing all
 /// values that are equal in the second. Both ElementPtrs MUST be MapElements.
 /// The returned ElementPtr will be a MapElement that only contains new and
 /// changed values (for ModuleCCSession and configuration update handlers).
 /// Raises a TypeError if a or b are not MapElements
 ConstElementPtr removeIdentical(ConstElementPtr a, ConstElementPtr b);
 
-/// \brief Merges the data from other into element.
+/// @brief Merges the data from other into element.
 /// (on the first level). Both elements must be
 /// MapElements.
 /// Every string,value pair in other is copied into element
@@ -732,78 +732,78 @@ ConstElementPtr removeIdentical(ConstElementPtr a, ConstElementPtr b);
 /// Raises a TypeError if either ElementPtr is not a MapElement
 void merge(ElementPtr element, ConstElementPtr other);
 
-/// \brief Copy the data up to a nesting level.
+/// @brief Copy the data up to a nesting level.
 ///
 /// The copy is a deep copy so nothing is shared if it is not
 /// under the given nesting level.
 ///
-/// \param from the pointer to the element to copy
-/// \param level nesting level (default is 100, 0 means shallow copy,
+/// @param from the pointer to the element to copy
+/// @param level nesting level (default is 100, 0 means shallow copy,
 /// negative means outbound and perhaps looping forever).
-/// \return a pointer to a fresh copy
+/// @return a pointer to a fresh copy
 /// \throw raises a BadValue is a null pointer occurs.
 ElementPtr copy(ConstElementPtr from, int level = 100); 
 
-/// \brief Compares the data with other using unordered lists
+/// @brief Compares the data with other using unordered lists
 ///
 /// This comparison function handles lists (JSON arrays) as
 /// unordered multi sets (multi means an item can occurs more
 /// than once as soon as it occurs the same number of times).
 bool isEquivalent(ConstElementPtr a, ConstElementPtr b);
 
-/// \brief Pretty prints the data into stream.
+/// @brief Pretty prints the data into stream.
 ///
-/// This operator converts the \c ConstElementPtr into a string and
-/// inserts it into the output stream \c out with an initial
-/// indentation \c indent and add at each level \c step spaces.
+/// This operator converts the @c ConstElementPtr into a string and
+/// inserts it into the output stream @c out with an initial
+/// indentation @c indent and add at each level @c step spaces.
 ///
-/// \param element A \c ConstElementPtr to pretty print
-/// \param out A \c std::ostream on which the print operation is performed
-/// \param indent An initial number of spaces to add each new line
-/// \param step A number of spaces to add to indentation at a new level
+/// @param element A @c ConstElementPtr to pretty print
+/// @param out A @c std::ostream on which the print operation is performed
+/// @param indent An initial number of spaces to add each new line
+/// @param step A number of spaces to add to indentation at a new level
 void prettyPrint(ConstElementPtr element, std::ostream& out,
                  unsigned indent = 0, unsigned step = 2);
 
-/// \brief Pretty prints the data into string
+/// @brief Pretty prints the data into string
 ///
-/// This operator converts the \c ConstElementPtr into a string with
-/// an initial indentation \c indent and add at each level \c step spaces.
+/// This operator converts the @c ConstElementPtr into a string with
+/// an initial indentation @c indent and add at each level @c step spaces.
 ///
-/// \param element A \c ConstElementPtr to pretty print
-/// \param indent An initial number of spaces to add each new line
-/// \param step A number of spaces to add to indentation at a new level
-/// \return a string where element was pretty printed
+/// @param element A @c ConstElementPtr to pretty print
+/// @param indent An initial number of spaces to add each new line
+/// @param step A number of spaces to add to indentation at a new level
+/// @return a string where element was pretty printed
 std::string prettyPrint(ConstElementPtr element,
                         unsigned indent = 0, unsigned step = 2);
 
 ///
-/// \brief Insert Element::Position as a string into stream.
+/// @brief Insert Element::Position as a string into stream.
 ///
-/// This operator converts the \c Element::Position into a string and
-/// inserts it into the output stream \c out.
+/// This operator converts the @c Element::Position into a string and
+/// inserts it into the output stream @c out.
 ///
-/// \param out A \c std::ostream object on which the insertion operation is
+/// @param out A @c std::ostream object on which the insertion operation is
 /// performed.
-/// \param pos The \c Element::Position structure to insert.
-/// \return A reference to the same \c std::ostream object referenced by
-/// parameter \c out after the insertion operation.
+/// @param pos The @c Element::Position structure to insert.
+/// @return A reference to the same @c std::ostream object referenced by
+/// parameter @c out after the insertion operation.
 std::ostream& operator<<(std::ostream& out, const Element::Position& pos);
 
 ///
-/// \brief Insert the Element as a string into stream.
+/// @brief Insert the Element as a string into stream.
 ///
-/// This method converts the \c ElementPtr into a string with
-/// \c Element::str() and inserts it into the
-/// output stream \c out.
+/// This method converts the @c ElementPtr into a string with
+/// @c Element::str() and inserts it into the
+/// output stream @c out.
 ///
 /// This function overloads the global operator<< to behave as described in
-/// ostream::operator<< but applied to \c ElementPtr objects.
+/// ostream::operator<< but applied to @c ElementPtr objects.
 ///
-/// \param out A \c std::ostream object on which the insertion operation is
+/// @param out A @c std::ostream object on which the insertion operation is
 /// performed.
-/// \param e The \c ElementPtr object to insert.
-/// \return A reference to the same \c std::ostream object referenced by
-/// parameter \c out after the insertion operation.
+/// @param e The @c ElementPtr object to insert.
+/// @return A reference to the same @c std::ostream object referenced by
+/// parameter @c out after the insertion operation.
 std::ostream& operator<<(std::ostream& out, const Element& e);
 
 bool operator==(const Element& a, const Element& b);