Improve documentation for UI classes

src/qt/notificator.h

@@ -11,33 +11,34 @@ class QDBusInterface;
 #endif
 QT_END_NAMESPACE
 
-// Cross-platform desktop notification client
+/** Cross-platform desktop notification client. */
 class Notificator: public QObject
 {
     Q_OBJECT
 public:
-    // Create a new notificator
-    // Ownership of trayIcon is not transferred to this object
+    /** Create a new notificator.
+       @note Ownership of trayIcon is not transferred to this object.
+    */
     Notificator(const QString &programName=QString(), QSystemTrayIcon *trayIcon=0, QWidget *parent=0);
     ~Notificator();
 
     // Message class
     enum Class
     {
-        Information,
-        Warning,
-        Critical,
+        Information,         /**< Informational message */
+        Warning,             /**< Notify user of potential problem */
+        Critical             /**< An error occured */
     };
 
 public slots:
 
-    /* Show notification message.
-     *
-     *  cls: general message class
-     *  title: title shown with message
-     *  text: message content
-     *  icon: optional icon to show with message
-     *  millisTimeout: notification timeout in milliseconds (default 10 seconds)
+    /** Show notification message.
+       @param[in] cls    general message class
+       @param[in] title  title shown with message
+       @param[in] text   message content
+       @param[in] icon   optional icon to show with message
+       @param[in] millisTimeout notification timeout in milliseconds (defaults to 10 seconds)
+       @note Platform implementations are free to ignore any of the provided fields except for \a text.
      */
     void notify(Class cls, const QString &title, const QString &text,
                 const QIcon &icon = QIcon(), int millisTimeout = 10000);
@@ -45,10 +46,10 @@ public slots:
 private:
     QWidget *parent;
     enum Mode {
-        None,
-        Freedesktop, // Use DBus org.freedesktop.Notifications
-        QSystemTray, // Use QSystemTray::showMessage
-        Growl // Use the Growl notification system (Mac only)
+        None,        /**< Ignore informational notifications, and show a modal pop-up dialog for Critical notifications. */
+        Freedesktop, /**< Use DBus org.freedesktop.Notifications */
+        QSystemTray, /**< Use QSystemTray::showMessage */
+        Growl        /**< Use the Growl notification system (Mac only) */
     };
     QString programName;
     Mode mode;