Doc comment cleanup of '@brief'.

(bzr r10120)

2 files changed, 119 insertions, 100 deletions

diff --git a/src/preferences.cpp b/src/preferences.cpp
index 4a9944140..94fbc7257 100644
--- a/src/preferences.cpp
+++ b/src/preferences.cpp
@@ -1,5 +1,5 @@
 /** @file
- * @brief  Singleton class to access the preferences file - implementation
+ * Singleton class to access the preferences file - implementation.
  */
 /* Authors:
  *   Krzysztof Kosiński <tweenk.pl@gmail.com>
@@ -59,7 +59,7 @@ static void file_add_recent(gchar const *uri)
 // private inner class definition
 
 /**
- * @brief XML - prefs observer bridge
+ * XML - prefs observer bridge.
  *
  * This is an XML node observer that watches for changes in the XML document storing the preferences.
  * It is used to implement preference observers.
@@ -110,7 +110,7 @@ Preferences::~Preferences()
 }
 
 /**
- * @brief Load internal defaults
+ * Load internal defaults.
  *
  * In the future this will try to load the system-wide file before falling
  * back to the internal defaults.
@@ -121,7 +121,7 @@ void Preferences::_loadDefaults()
 }
 
 /**
- * @brief Load the user's customized preferences
+ * Load the user's customized preferences.
  *
  * Tries to load the user's preferences.xml file. If there is none, creates it.
  */
@@ -255,7 +255,7 @@ static void migrateDetails( Inkscape::XML::Document *from, Inkscape::XML::Docume
 }
 
 /**
- * @brief Flush all pref changes to the XML file
+ * Flush all pref changes to the XML file.
  */
 void Preferences::save()
 {
@@ -364,9 +364,10 @@ void Preferences::migrate( std::string const& legacyDir, std::string const& pref
 // Now for the meat.
 
 /**
- * @brief Get names of all entries in the specified path
- * @param path Preference path to query
- * @return A vector containing all entries in the given directory
+ * Get names of all entries in the specified path.
+ *
+ * @param path Preference path to query.
+ * @return A vector containing all entries in the given directory.
  */
 std::vector<Preferences::Entry> Preferences::getAllEntries(Glib::ustring const &path)
 {
@@ -383,9 +384,10 @@ std::vector<Preferences::Entry> Preferences::getAllEntries(Glib::ustring const &
 }
 
 /**
- * @brief Get the paths to all subdirectories of the specified path
- * @param path Preference path to query
- * @return A vector containing absolute paths to all subdirectories in the given path
+ * Get the paths to all subdirectories of the specified path.
+ *
+ * @param path Preference path to query.
+ * @return A vector containing absolute paths to all subdirectories in the given path.
  */
 std::vector<Glib::ustring> Preferences::getAllDirs(Glib::ustring const &path)
 {
@@ -411,9 +413,10 @@ Preferences::Entry const Preferences::getEntry(Glib::ustring const &pref_path)
 // setter methods
 
 /**
- * @brief Set a boolean attribute of a preference
- * @param pref_path Path of the preference to modify
- * @param value The new value of the pref attribute
+ * Set a boolean attribute of a preference.
+ *
+ * @param pref_path Path of the preference to modify.
+ * @param value The new value of the pref attribute.
  */
 void Preferences::setBool(Glib::ustring const &pref_path, bool value)
 {
@@ -424,9 +427,10 @@ void Preferences::setBool(Glib::ustring const &pref_path, bool value)
 }
 
 /**
- * @brief Set an integer attribute of a preference
- * @param pref_path Path of the preference to modify
- * @param value The new value of the pref attribute
+ * Set an integer attribute of a preference.
+ *
+ * @param pref_path Path of the preference to modify.
+ * @param value The new value of the pref attribute.
  */
 void Preferences::setInt(Glib::ustring const &pref_path, int value)
 {
@@ -436,9 +440,10 @@ void Preferences::setInt(Glib::ustring const &pref_path, int value)
 }
 
 /**
- * @brief Set a floating point attribute of a preference
- * @param pref_path Path of the preference to modify
- * @param value The new value of the pref attribute
+ * Set a floating point attribute of a preference.
+ *
+ * @param pref_path Path of the preference to modify.
+ * @param value The new value of the pref attribute.
  */
 void Preferences::setDouble(Glib::ustring const &pref_path, double value)
 {
@@ -455,9 +460,10 @@ void Preferences::setColor(Glib::ustring const &pref_path, guint32 value)
 }
 
 /**
- * @brief Set a string attribute of a preference
- * @param pref_path Path of the preference to modify
- * @param value The new value of the pref attribute
+ * Set a string attribute of a preference.
+ *
+ * @param pref_path Path of the preference to modify.
+ * @param value The new value of the pref attribute.
  */
 void Preferences::setString(Glib::ustring const &pref_path, Glib::ustring const &value)
 {
@@ -486,7 +492,7 @@ void Preferences::mergeStyle(Glib::ustring const &pref_path, SPCSSAttr *style)
 namespace {
 
 /**
- * @brief Structure that holds additional information for registered Observers
+ * Structure that holds additional information for registered Observers.
  */
 struct _ObserverData {
     Inkscape::XML::Node *_node; ///< Node at which the wrapping PrefNodeObserver is registered
@@ -542,7 +548,7 @@ void Preferences::PrefNodeObserver::notifyAttributeChanged(XML::Node &node, GQua
 }
 
 /**
- * @brief Find the XML node to observe
+ * Find the XML node to observe.
  */
 XML::Node *Preferences::_findObserverNode(Glib::ustring const &pref_path, Glib::ustring &node_key, Glib::ustring &attr_key, bool create)
 {
@@ -613,11 +619,12 @@ void Preferences::removeObserver(Observer &o)
 
 
 /**
- * @brief Get the XML node corresponding to the given pref key
- * @param pref_key Preference key (path) to get
- * @param create Whether to create the corresponding node if it doesn't exist
- * @param separator The character used to separate parts of the pref key
- * @return XML node corresponding to the specified key
+ * Get the XML node corresponding to the given pref key.
+ *
+ * @param pref_key Preference key (path) to get.
+ * @param create Whether to create the corresponding node if it doesn't exist.
+ * @param separator The character used to separate parts of the pref key.
+ * @return XML node corresponding to the specified key.
  *
  * Derived from former inkscape_get_repr(). Private because it assumes that the backend is
  * a flat XML file, which may not be the case e.g. if we are using GConf (in future).
diff --git a/src/preferences.h b/src/preferences.h
index 5e1ccf9d6..c79a7377d 100644
--- a/src/preferences.h
+++ b/src/preferences.h
@@ -1,5 +1,5 @@
 /** @file
- * @brief  Singleton class to access the preferences file in a convenient way.
+ * Singleton class to access the preferences file in a convenient way.
  */
 /* Authors:
  *   Krzysztof Kosi_ski <tweenk.pl@gmail.com>
@@ -33,7 +33,7 @@ public:
 };
 
 /**
- * @brief Preference storage class.
+ * Preference storage class.
  *
  * This is a singleton that allows one to access the user preferences stored in
  * the preferences.xml file. The preferences are stored in a file system-like
@@ -63,7 +63,7 @@ public:
     class Observer;
 
     /**
-     * @brief Base class for preference observers
+     * Base class for preference observers.
      *
      * If you want to watch for changes in the preferences, you'll have to
      * derive a class from this one and override the notify() method.
@@ -73,7 +73,7 @@ public:
     public:
 
         /**
-         * @brief Constructor.
+         * Constructor.
          *
          * Since each Observer is assigned to a single path, the base
          * constructor takes this path as an argument. This prevents one from
@@ -88,15 +88,16 @@ public:
          * Watching the preference "/options/some_group/some_option" will only
          * generate notifications when this single preference changes.
          *
-         * @param path Preference path the observer should watch
+         * @param path Preference path the observer should watch.
          */
         Observer(Glib::ustring const &path);
         virtual ~Observer();
 
         /**
-         * @brief Notification about a preference change
+         * Notification about a preference change.
+         *
          * @param new_val  Entry object containing information about
-         *                 the modified preference
+         *                 the modified preference.
          */
         virtual void notify(Preferences::Entry const &new_val) = 0;
 
@@ -107,7 +108,7 @@ public:
 
 
     /**
-     * @brief Data type representing a typeless value of a preference
+     * Data type representing a typeless value of a preference.
      *
      * This is passed to the observer in the notify() method.
      * To retrieve useful data from it, use its member functions. Setting
@@ -122,75 +123,80 @@ public:
         Entry(Entry const &other) : _pref_path(other._pref_path), _value(other._value) {}
 
         /**
-         * @brief Check whether the received entry is valid.
+         * Check whether the received entry is valid.
+         *
          * @return If false, the default value will be returned by the getters.
          */
         bool isValid() const { return _value != NULL; }
 
         /**
-         * @brief Interpret the preference as a Boolean value.
-         * @param def Default value if the preference is not set
+         * Interpret the preference as a Boolean value.
+         *
+         * @param def Default value if the preference is not set.
          */
         inline bool getBool(bool def=false) const;
 
         /**
-         * @brief Interpret the preference as an integer.
-         * @param def Default value if the preference is not set
+         * Interpret the preference as an integer.
+         *
+         * @param def Default value if the preference is not set.
          */
         inline int getInt(int def=0) const;
 
         /**
-         * @brief Interpret the preference as a limited integer.
+         * Interpret the preference as a limited integer.
          *
          * This method will return the default value if the interpreted value is
          * larger than @c max or smaller than @c min. Do not use to store
          * Boolean values as integers.
          *
-         * @param def Default value if the preference is not set
-         * @param min Minimum value allowed to return
-         * @param max Maximum value allowed to return
+         * @param def Default value if the preference is not set.
+         * @param min Minimum value allowed to return.
+         * @param max Maximum value allowed to return.
          */
         inline int getIntLimited(int def=0, int min=INT_MIN, int max=INT_MAX) const;
 
         /**
-         * @brief Interpret the preference as a floating point value.
-         * @param def Default value if the preference is not set
+         * Interpret the preference as a floating point value.
+         *
+         * @param def Default value if the preference is not set.
          */
         inline double getDouble(double def=0.0) const;
 
         /**
-         * @brief Interpret the preference as a limited floating point value.
+         * Interpret the preference as a limited floating point value.
          *
          * This method will return the default value if the interpreted value is
          * larger than @c max or smaller than @c min.
          *
-         * @param def Default value if the preference is not set
-         * @param min Minimum value allowed to return
-         * @param max Maximum value allowed to return
+         * @param def Default value if the preference is not set.
+         * @param min Minimum value allowed to return.
+         * @param max Maximum value allowed to return.
          */
         inline double getDoubleLimited(double def=0.0, double min=DBL_MIN, double max=DBL_MAX) const;
 
         /**
-         * @brief Interpret the preference as an UTF-8 string.
+         * Interpret the preference as an UTF-8 string.
          *
          * To store a filename, convert it using Glib::filename_to_utf8().
          */
         inline Glib::ustring getString() const;
 
         /**
-         * @brief Interpret the preference as an RGBA color value.
+         * Interpret the preference as an RGBA color value.
          */
         inline guint32 getColor(guint32 def) const;
 
         /**
-         * @brief Interpret the preference as a CSS style.
+         * Interpret the preference as a CSS style.
+         *
          * @return A CSS style that has to be unrefed when no longer necessary. Never NULL.
          */
         inline SPCSSAttr *getStyle() const;
 
         /**
-         * @brief Interpret the preference as a CSS style with directory-based
-         *        inheritance
+         * Interpret the preference as a CSS style with directory-based
+         * inheritance.
          *
          * This function will look up the preferences with the same entry name
          * in ancestor directories and return the inherited CSS style.
@@ -200,12 +206,12 @@ public:
         inline SPCSSAttr *getInheritedStyle() const;
 
         /**
-         * @brief Get the full path of the preference described by this Entry.
+         * Get the full path of the preference described by this Entry.
          */
         Glib::ustring const &getPath() const { return _pref_path; }
 
         /**
-         * @brief Get the last component of the preference's path
+         * Get the last component of the preference's path.
          *
          * E.g. For "/options/some_group/some_option" it will return "some_option".
          */
@@ -220,7 +226,7 @@ public:
     // utility methods
 
     /**
-     * @brief Save all preferences to the hard disk.
+     * Save all preferences to the hard disk.
      *
      * For some backends, the preferences may be saved as they are modified.
      * Not calling this method doesn't guarantee the preferences are unmodified
@@ -229,13 +235,13 @@ public:
     void save();
 
     /**
-     * @brief Check whether saving the preferences will have any effect.
+     * Check whether saving the preferences will have any effect.
      */
     bool isWritable() { return _writable; }
     /*@}*/
 
     /**
-     * @brief Return details of the last encountered error, if any.
+     * Return details of the last encountered error, if any.
      *
      * This method will return true if an error has been encountered, and fill
      * in the primary and secondary error strings of the last error. If an error
@@ -254,7 +260,7 @@ public:
      */
 
     /**
-     * @brief Get all entries from the specified directory
+     * Get all entries from the specified directory.
      *
      * This method will return a vector populated with preference entries
      * from the specified directory. Subdirectories will not be represented.
@@ -262,7 +268,7 @@ public:
     std::vector<Entry> getAllEntries(Glib::ustring const &path);
 
     /**
-     * @brief Get all subdirectories of the specified directory
+     * Get all subdirectories of the specified directory.
      *
      * This will return a vector populated with full paths to the subdirectories
      * present in the specified @c path.
@@ -276,59 +282,63 @@ public:
      */
 
     /**
-     * @brief Retrieve a Boolean value
-     * @param pref_path Path to the retrieved preference
-     * @param def The default value to return if the preference is not set
+     * Retrieve a Boolean value.
+     *
+     * @param pref_path Path to the retrieved preference.
+     * @param def The default value to return if the preference is not set.
      */
     bool getBool(Glib::ustring const &pref_path, bool def=false) {
         return getEntry(pref_path).getBool(def);
     }
 
     /**
-     * @brief Retrieve an integer
-     * @param pref_path Path to the retrieved preference
-     * @param def The default value to return if the preference is not set
+     * Retrieve an integer.
+     *
+     * @param pref_path Path to the retrieved preference.
+     * @param def The default value to return if the preference is not set.
      */
     int getInt(Glib::ustring const &pref_path, int def=0) {
         return getEntry(pref_path).getInt(def);
     }
 
     /**
-     * @brief Retrieve a limited integer
+     * Retrieve a limited integer.
      *
      * The default value is returned if the actual value is larger than @c max
      * or smaller than @c min. Do not use to store Boolean values.
      *
-     * @param pref_path Path to the retrieved preference
-     * @param def The default value to return if the preference is not set
-     * @param min Minimum value to return
-     * @param max Maximum value to return
+     * @param pref_path Path to the retrieved preference.
+     * @param def The default value to return if the preference is not set.
+     * @param min Minimum value to return.
+     * @param max Maximum value to return.
      */
     int getIntLimited(Glib::ustring const &pref_path, int def=0, int min=INT_MIN, int max=INT_MAX) {
         return getEntry(pref_path).getIntLimited(def, min, max);
     }
+
     double getDouble(Glib::ustring const &pref_path, double def=0.0) {
         return getEntry(pref_path).getDouble(def);
     }
 
     /**
-     * @brief Retrieve a limited floating point value
+     * Retrieve a limited floating point value.
      *
      * The default value is returned if the actual value is larger than @c max
      * or smaller than @c min.
      *
-     * @param pref_path Path to the retrieved preference
-     * @param def The default value to return if the preference is not set
-     * @param min Minimum value to return
-     * @param max Maximum value to return
+     * @param pref_path Path to the retrieved preference.
+     * @param def The default value to return if the preference is not set.
+     * @param min Minimum value to return.
+     * @param max Maximum value to return.
      */
     double getDoubleLimited(Glib::ustring const &pref_path, double def=0.0, double min=DBL_MIN, double max=DBL_MAX) {
         return getEntry(pref_path).getDoubleLimited(def, min, max);
     }
 
     /**
-     * @brief Retrieve an UTF-8 string
-     * @param pref_path Path to the retrieved preference
+     * Retrieve an UTF-8 string.
+     *
+     * @param pref_path Path to the retrieved preference.
      */
     Glib::ustring getString(Glib::ustring const &pref_path) {
         return getEntry(pref_path).getString();
@@ -339,8 +349,9 @@ public:
     }
 
     /**
-     * @brief Retrieve a CSS style
-     * @param pref_path Path to the retrieved preference
+     * Retrieve a CSS style.
+     *
+     * @param pref_path Path to the retrieved preference.
      * @return A CSS style that has to be unrefed after use.
      */
     SPCSSAttr *getStyle(Glib::ustring const &pref_path) {
@@ -348,13 +359,13 @@ public:
     }
 
     /**
-     * @brief Retrieve an inherited CSS style
+     * Retrieve an inherited CSS style.
      *
      * This method will look up preferences with the same entry name in ancestor
      * directories and return a style obtained by inheriting properties from
      * ancestor styles.
      *
-     * @param pref_path Path to the retrieved preference
+     * @param pref_path Path to the retrieved preference.
      * @return An inherited CSS style that has to be unrefed after use.
      */
     SPCSSAttr *getInheritedStyle(Glib::ustring const &pref_path) {
@@ -362,7 +373,7 @@ public:
     }
 
     /**
-     * @brief Retrieve a preference entry without specifying its type
+     * Retrieve a preference entry without specifying its type.
      */
     Entry const getEntry(Glib::ustring const &pref_path);
     /*@}*/
@@ -373,37 +384,37 @@ public:
      */
 
     /**
-     * @brief Set a Boolean value
+     * Set a Boolean value.
      */
     void setBool(Glib::ustring const &pref_path, bool value);
 
     /**
-     * @brief Set an integer value
+     * Set an integer value.
      */
     void setInt(Glib::ustring const &pref_path, int value);
 
     /**
-     * @brief Set a floating point value
+     * Set a floating point value.
      */
     void setDouble(Glib::ustring const &pref_path, double value);
 
     /**
-     * @brief Set an UTF-8 string value
+     * Set an UTF-8 string value.
      */
     void setString(Glib::ustring const &pref_path, Glib::ustring const &value);
 
     /**
-     * @brief Set an RGBA color value
+     * Set an RGBA color value.
      */
     void setColor(Glib::ustring const &pref_path, guint32 value);
 
     /**
-     * @brief Set a CSS style
+     * Set a CSS style.
      */
     void setStyle(Glib::ustring const &pref_path, SPCSSAttr *style);
 
     /**
-     * @brief Merge a CSS style with the current preference value
+     * Merge a CSS style with the current preference value.
      *
      * This method is similar to setStyle(), except that it merges the style
      * rather than replacing it. This means that if @c style doesn't have
@@ -419,12 +430,12 @@ public:
      */
 
     /**
-     * @brief Register a preference observer
+     * Register a preference observer.
      */
     void addObserver(Observer &);
 
     /**
-     * @brief Remove an observer an prevent further notifications to it.
+     * Remove an observer an prevent further notifications to it.
      */
     void removeObserver(Observer &);
     /*@}*/
@@ -441,7 +452,7 @@ public:
     static void migrate( std::string const& legacyDir, std::string const& prefdir );
 
     /**
-     * @brief Access the singleton Preferences object.
+     * Access the singleton Preferences object.
      */
     static Preferences *get() {
         if (!_instance) {
@@ -453,8 +464,9 @@ public:
     void setErrorHandler(ErrorReporter* handler);
 
     /**
-     * @brief Unload all preferences
-     * @param save Whether to save the preferences; defaults to true
+     * Unload all preferences.
+     *
+     * @param save Whether to save the preferences; defaults to true.
      *
      * This deletes the singleton object. Calling get() after this function
      * will reinstate it, so you shouldn't. Pass false as the parameter