From kde-commits  Fri Mar 31 21:26:57 2006
From: Bram Schoenmakers <bramschoenmakers () kde ! nl>
Date: Fri, 31 Mar 2006 21:26:57 +0000
To: kde-commits
Subject: playground/utils/rsibreak/src
Message-Id: <1143840417.652762.25646.nullmailer () svn ! kde ! org>
X-MARC-Message: https://marc.info/?l=kde-commits&m=114384042525318

SVN commit 525128 by bram:

More APIDOX fun.



 M  +30 -0     rsiglobals.h  
 M  +31 -0     rsistatitem.h  
 M  +20 -20    rsistats.h  


--- trunk/playground/utils/rsibreak/src/rsiglobals.h #525127:525128
@@ -55,11 +55,24 @@
 {
   Q_OBJECT
   public:
+    /** Default constructor. */
     RSIGlobals( QObject *parent = 0, const char *name = 0 );
+
+    /** Default destructor. */
     ~RSIGlobals();
 
+    /**
+     * Returns an instance of RSIGlobals. Never create your own instance
+     * of RSIGlobals, but use this method instead to get the one and only
+     * instance.
+     */
     static RSIGlobals *instance();
 
+    /**
+     * Returns the one and only statistics component.
+     *
+     * @see RSIStats
+     */
     RSIStats *stats() { return m_stats; }
 
     /**
@@ -76,12 +89,29 @@
      */
     QString formatSeconds(const int seconds);
 
+    /**
+     * Returns a reference to the mapping containing all intervals.
+     * These intervals define when a tiny or big break should occur and for how
+     * long.
+     */
     QMap<QString,int> &intervals() { return m_intervals; }
 
+    /**
+     * This function returns a color ranging from green to red.
+     * The more red, the more the user needs a tiny break.
+     */
     QColor getTinyBreakColor() const;
+
+    /**
+     * This function returns a color ranging from green to red.
+     * The more red, the more the user needs a tiny break.
+     */
     QColor getBigBreakColor() const;
 
   public slots:
+    /**
+     * Reads the configuration.
+     */
     void slotReadConfig();
 
   private:
--- trunk/playground/utils/rsibreak/src/rsistatitem.h #525127:525128
@@ -26,18 +26,49 @@
 
 #include "rsiglobals.h"
 
+/**
+ * This class represents one statistic.
+ * It consists of a value, a description and a list
+ * of items which have this statistic as a dependency.
+ */
 class RSIStatItem
 {
   public:
+    /**
+     * Constructor. Pass a @p description along to give the
+     * statistic a useful description. It will be visible in the
+     * statistics widget.
+     * @param description A i18n()'d text representing this statistic's meaning.
+     */
     RSIStatItem( const QString &description = QString::null );
+
+    /** Default destructor. */
     ~RSIStatItem();
 
+    /** Retrieve the item's description in QLabel format. */
     QLabel *getDescription() const { return m_description; }
+
+    /** Retrieve the item's value in QVariant format. */
     QVariant getValue()      const { return m_value; }
 
+    /**
+     * Sets the value of this item.
+     * @param v The new value of this statistic item.
+     *
+     * @see QVariant documentation for supported types of values.
+     */
     void setValue( QVariant v ) { m_value = v; }
 
+    /**
+     * When other statistics depend on this statistic item, it should
+     * be added to this list. When this statistic is updated, it will
+     * iterate through the list of derived statistics and update them.
+     */
     void addDerivedItem( RSIStat stat );
+
+    /**
+     * Returns the list of derived statistics.
+     */
     QValueList<RSIStat> getDerivedItems() const { return m_derived; }
 
   private:
--- trunk/playground/utils/rsibreak/src/rsistats.h #525127:525128
@@ -41,7 +41,7 @@
   The last step involves to actually put it in the statistics widget. Use
   the addStat() method there.
 
-  @see RSIGlobal
+  @see RSIGlobals
   @see RSIStatDialog
   @see RSITimer
 */
@@ -60,21 +60,21 @@
     void increaseStat( RSIStat stat, int delta = 1 );
 
     /**
-      Sets the value of a statistic.
-      @param stat The statistic in question.
-      @param stat The value to be assigned to the statistic. In QVariant format.
-      @param stat If true, the value will only be assigned if the current
-      value is lower than the given @p value.
-    */
+     * Sets the value of a statistic.
+     * @param stat The statistic in question.
+     * @param stat The value to be assigned to the statistic. In QVariant format.
+     * @param stat If true, the value will only be assigned if the current
+     * value is lower than the given @p value.
+     */
     void setStat( RSIStat stat, QVariant val, bool ifmax = false );
 
     /** Returns a description for the given @p stat. */
     QLabel *getDescription( RSIStat stat ) const;
 
     /**
-      Updates all labels to the current value of their corresponding
-      statistic.
-    */
+     * Updates all labels to the current value of their corresponding
+     * statistic.
+     */
     void updateLabels();
 
     /** Gets the value given the @p stat.*/
@@ -88,22 +88,22 @@
     void updateLabel( RSIStat stat );
 
     /**
-      Some statistics are calculated based on values of other statistics.
-      This function updates all statistics with @p stat as dependency.
-    */
+     * Some statistics are calculated based on values of other statistics.
+     * This function updates all statistics with @p stat as dependency.
+     */
     void updateDependentStats( RSIStat stat );
 
     /**
-      Updates the given statistic.
-      @param stat The statistic you've just assigned a value to.
-      @param updateDerived If true, update the derived statistics when
-      calling this function.
-    */
+     * Updates the given statistic.
+     * @param stat The statistic you've just assigned a value to.
+     * @param updateDerived If true, update the derived statistics when
+     * calling this function.
+     */
     void updateStat( RSIStat stat, bool updateDerived = true );
 
     /**
-      Retrieves What's This? text for a given statistic @p stat.
-    */
+     * Retrieves What's This? text for a given statistic @p stat.
+     */
     QString getWhatsThisText( RSIStat stat ) const;
 
 private: