Added documentation

diff --git a/src/map/mapengine.h b/src/map/mapengine.h
index 02a3f6a..810f25f 100644 (file)
--- a/src/map/mapengine.h
+++ b/src/map/mapengine.h
@@ -446,7 +446,7 @@ private:
     GPSLocationItem *m_gpsLocationItem;         ///< Item pointing current location from GPS
     MapFetcher *m_mapFetcher;                   ///< Fetcher for map tiles
     MapScene *m_mapScene;                       ///< Scene for map tiles
-    MapScroller *m_scroller;
+    MapScroller *m_scroller;                    ///< Kinetic scroller
     OwnLocationItem *m_ownLocation;             ///< Item to show own location
 };
 

diff --git a/src/map/mapscroller.cpp b/src/map/mapscroller.cpp
index 7cb3922..65e738e 100644 (file)
--- a/src/map/mapscroller.cpp
+++ b/src/map/mapscroller.cpp
@@ -43,5 +43,7 @@ void MapScroller::updateCurrentValue(const QVariant &value)
 {
     qDebug() << __PRETTY_FUNCTION__;
 
+    Q_ASSERT(!value.toPoint().isNull());
+
     emit coordinateUpdated(value.toPoint());
 }

diff --git a/src/map/mapscroller.h b/src/map/mapscroller.h
index 2593a10..76297a2 100644 (file)
--- a/src/map/mapscroller.h
+++ b/src/map/mapscroller.h
@@ -26,24 +26,74 @@
 #include <QPoint>
 #include <QVariantAnimation>
 
+/**
+* @brief Map scroller
+*
+* Used for kinetic and smooth scroll effects. Class implementation is following the singleton
+* desing pattern.
+*
+* @author Sami Rämö - sami.ramo@ixonos.com
+*/
 class MapScroller : public QVariantAnimation
 {
     Q_OBJECT
 
 private:
-    /// @todo remove default constructor after caller does set easing curve
-    MapScroller(); // {}
+    /**
+    * @brief Constructor in not accessible because class is using singleton design pattern.
+    *
+    * @todo remove default constructor implementation after caller does set the easing curve
+    */
+    MapScroller();
+
+    /**
+    * @brief Destructor in not accessible because class is using singleton design pattern.
+    */
     ~MapScroller() {}
-    MapScroller(const MapScroller &);             // intentionally undefined
-    MapScroller & operator=(const MapScroller &); // intentionally undefined
 
+    /**
+    * @brief Copy constructor in not accessible because class is using singleton design pattern.
+    */
+    MapScroller(const MapScroller &);
+
+    /**
+    * @brief Assignment operator in not accessible because class is using singleton design pattern.
+    */
+    MapScroller & operator=(const MapScroller &);
+
+/*******************************************************************************
+ * BASE CLASS INHERITED AND REIMPLEMENTED MEMBER FUNCTIONS
+ ******************************************************************************/
 private:
+    /**
+    * @brief Reimplemented from QVariantAnimation::updateCurrentValue()
+    *
+    * Called every time the animation's current value changes
+    *
+    * @param value New value
+    */
     void updateCurrentValue(const QVariant &value);
 
+/*******************************************************************************
+ * MEMBER FUNCTIONS AND SLOTS
+ ******************************************************************************/
 public:
+    /**
+    * @brief Get reference to instance of this class
+    *
+    * @return reference to instance of this class
+    */
     static MapScroller &getInstance();
 
+/*******************************************************************************
+ * SIGNALS
+ ******************************************************************************/
 signals:
+    /**
+    * @brief Signal if emitted when coordinate value is updated
+    *
+    * @param coordinate New coordinate value
+    */
     void coordinateUpdated(QPoint coordinate);
 };
 

diff --git a/src/map/mapview.h b/src/map/mapview.h
index a20bcab..ac2e207 100644 (file)
--- a/src/map/mapview.h
+++ b/src/map/mapview.h
@@ -75,6 +75,10 @@ private:
     * Does calculate mouse movement delta from last event position and new view center
     * based on that delta. Saves current event position for next round. Emits viewScrolled
     * signal and doesn't actually scroll the view.
+    *
+    * Saves mouse movement deltas and durations for last few move events to be used for
+    * calculating the kinetic scrolling speed.
+    *
     * @param event Mouse event
     */
     void mouseMoveEvent(QMouseEvent *event);
@@ -82,11 +86,24 @@ private:
     /**
     * @brief Event handler for mouse press events
     *
-    * Saves inial values for mouse and scene location for dragging view.
+    * Saves inial values for mouse and scene location for dragging the view. Does stop currently
+    * running kinetic scroll effect.
+    *
     * @param event Mouse event
     */
     void mousePressEvent(QMouseEvent *event);
 
+    /**
+    * @brief Event handler for mouse release events
+    *
+    * Set up and start kinetic scrolling effect if time elapsed from last mouseMoveEvent is below
+    * the limit and drag length is over the limit.
+    *
+    * Kinetic scroll distance is calculated based on mouse movement event values saved in
+    * mouseMoveEvent().
+    *
+    * @param event Mouse event
+    */
     void mouseReleaseEvent(QMouseEvent *event);
 
 /*******************************************************************************
@@ -151,20 +168,20 @@ signals:
  * DATA MEMBERS
  ******************************************************************************/
 private:
-    int m_dragTime[VALUES];
-    int m_index;
-    int m_zoomLevel;
+    int m_dragTime[VALUES];               ///< Table of mouse event durations
+    int m_index;                          ///< Index of mouse event values tables
+    int m_zoomLevel;                      ///< Current zoom level
 
-    QPoint m_dragMovement[VALUES];
-    QPoint m_mouseLastScenePosition;               ///< Previous mouse event position
-    QPoint m_mouseLastViewPosition;
+    QPoint m_dragMovement[VALUES];        ///< Table of mouse event distances
+    QPoint m_mouseLastScenePosition;      ///< Previous mouse event position in the scene
+    QPoint m_mouseLastViewPosition;       ///< Previous mouse event position in the view
     QPoint m_scenePosition;               ///< New center position
 
     QPropertyAnimation *m_zoomAnimation;  ///< Zoom animation
 
-    QTime time;
+    QTime time;                           ///< Elapsed times in mouse events
 
-    MapScroller *m_scroller;
+    MapScroller *m_scroller;              ///< Kinetic scroller
 };
 
 #endif // MAPVIEW_H