More documentation fixes.

3 files changed, 70 insertions, 34 deletions

diff --git a/src/gui/graphicsview/qgraphicsitem.cpp b/src/gui/graphicsview/qgraphicsitem.cpp
index cbd4834..0dc227a 100644
--- a/src/gui/graphicsview/qgraphicsitem.cpp
+++ b/src/gui/graphicsview/qgraphicsitem.cpp
@@ -5790,27 +5790,61 @@ QVariant QGraphicsItem::inputMethodQuery(Qt::InputMethodQuery query) const
     return QVariant();
 }
 
-int QGraphicsItem::grabGesture(Qt::GestureType type)
+/*!
+    Subscribes the graphics item to the specified \a gesture type.
+
+    Returns the id of the gesture.
+
+    \sa releaseGesture(), setGestureEnabled()
+*/
+int QGraphicsItem::grabGesture(Qt::GestureType gesture)
 {
-    return grabGesture(qt_getStandardGestureTypeName(type));
+    return grabGesture(qt_getStandardGestureTypeName(gesture));
 }
 
-int QGraphicsItem::grabGesture(const QString &type)
+/*!
+    Subscribes the graphics item to the specified \a gesture type.
+
+    Returns the id of the gesture.
+
+    \sa releaseGesture(), setGestureEnabled()
+*/
+int QGraphicsItem::grabGesture(const QString &gesture)
 {
-    int id = qHash(type);
+    int id = qHash(gesture);
     QSet<int>::iterator it = d_ptr->gestures.find(id);
     if (it != d_ptr->gestures.end())
         return *it;
     d_ptr->gestures << id;
     if (d_ptr->scene)
         d_ptr->scene->d_func()->grabGesture(this, id);
+    return id;
 }
 
-void QGraphicsItem::releaseGesture(int id)
+/*!
+    Unsubscribes the graphics item from a gesture, which is specified
+    by the \a gestureId.
+
+    \sa grabGesture(), setGestureEnabled()
+*/
+void QGraphicsItem::releaseGesture(int gestureId)
 {
-    d_ptr->gestures.remove(id);
+    d_ptr->gestures.remove(gestureId);
     if (d_ptr->scene)
-        d_ptr->scene->d_func()->releaseGesture(this, id);
+        d_ptr->scene->d_func()->releaseGesture(this, gestureId);
+}
+
+/*!
+    If \a enable is true, the gesture with the given \a gestureId is
+    enabled; otherwise the gesture is disabled.
+
+    The id of the gesture is returned by the grabGesture().
+
+    \sa grabGesture(), releaseGesture()
+*/
+void QGraphicsItem::setGestureEnabled(int gestureId, bool enable)
+{
+    //###
 }
 
 /*!
diff --git a/src/gui/graphicsview/qgraphicsitem.h b/src/gui/graphicsview/qgraphicsitem.h
index 4e6e96d..37d8f78 100644
--- a/src/gui/graphicsview/qgraphicsitem.h
+++ b/src/gui/graphicsview/qgraphicsitem.h
@@ -338,9 +338,10 @@ public:
     QVariant data(int key) const;
     void setData(int key, const QVariant &value);
 
-    int grabGesture(Qt::GestureType type);
-    int grabGesture(const QString &type);
+    int grabGesture(Qt::GestureType gesture);
+    int grabGesture(const QString &gesture);
     void releaseGesture(int gestureId);
+    void setGestureEnabled(int gestureId, bool enable = true);
 
     enum {
         Type = 1,
diff --git a/src/gui/graphicsview/qgraphicssceneevent.cpp b/src/gui/graphicsview/qgraphicssceneevent.cpp
index 4f24a74..c79e30b 100644
--- a/src/gui/graphicsview/qgraphicssceneevent.cpp
+++ b/src/gui/graphicsview/qgraphicssceneevent.cpp
@@ -1727,18 +1727,24 @@ void QGraphicsSceneMoveEvent::setNewPos(const QPointF &pos)
     gestures with \l{QGraphicsItem::}{grabGesture()}.
 */
 
-
+/*!
+    Constructs a QGraphicsSceneGestureEvent.
+*/
 QGraphicsSceneGestureEvent::QGraphicsSceneGestureEvent()
     : QGraphicsSceneEvent(QEvent::GraphicsSceneGesture)
 {
 }
 
+/*!
+    Destroys a QGraphicsSceneGestureEvent.
+*/
 QGraphicsSceneGestureEvent::~QGraphicsSceneGestureEvent()
 {
 }
 
 /*!
-    Checks if the gesture event contains gesture of specific \a type.
+    Returns true if the gesture event contains gesture of specific \a
+    type; returns false otherwise.
 */
 bool QGraphicsSceneGestureEvent::contains(const QString &type) const
 {
@@ -1746,7 +1752,8 @@ bool QGraphicsSceneGestureEvent::contains(const QString &type) const
 }
 
 /*!
-    Checks if the gesture event contains gesture of specific \a type.
+    Returns true if the gesture event contains gesture of specific \a
+    type; returns false otherwise.
 */
 bool QGraphicsSceneGestureEvent::contains(Qt::GestureType type) const
 {
@@ -1754,7 +1761,7 @@ bool QGraphicsSceneGestureEvent::contains(Qt::GestureType type) const
 }
 
 /*!
-    Returns a list of gesture names that the event contains.
+    Returns a list of gesture names that this event contains.
 */
 QList<QString> QGraphicsSceneGestureEvent::gestureTypes() const
 {
@@ -1778,7 +1785,7 @@ const QGesture* QGraphicsSceneGestureEvent::gesture(Qt::GestureType type) const
 }
 
 /*!
-    Returns extended information about all triggered gestures.
+    Returns extended information about all gestures in the event.
 */
 QList<QSharedPointer<QGesture> > QGraphicsSceneGestureEvent::gestures() const
 {
@@ -1786,7 +1793,7 @@ QList<QSharedPointer<QGesture> > QGraphicsSceneGestureEvent::gestures() const
 }
 
 /*!
-    Returns a set of gesture names that used to be executed, but got
+    Returns a set of gesture names that used to be executed, but were
     cancelled (i.e. they were not finished properly).
 */
 QSet<QString> QGraphicsSceneGestureEvent::cancelledGestures() const
@@ -1795,8 +1802,9 @@ QSet<QString> QGraphicsSceneGestureEvent::cancelledGestures() const
 }
 
 /*!
-    Returns a set of gesture names that used to be executed, but got
-    cancelled (i.e. they were not finished properly).
+    Sets a list of gesture names \a cancelledGestures that used to be
+    executed, but were cancelled (i.e. they were not finished
+    properly).
 */
 void QGraphicsSceneGestureEvent::setCancelledGestures(const QSet<QString> &cancelledGestures)
 {
@@ -1807,13 +1815,10 @@ void QGraphicsSceneGestureEvent::setCancelledGestures(const QSet<QString> &cance
     Maps the point \a point, which is in a view coordinate system, to
     scene coordinate system, and returns the mapped coordinate.
 
-    \a Point is in coordinate system of the widget that received
+    A \a point is in coordinate system of the widget that received
     gesture event.
 
-    \sa mapToScene(const QRect &rect),
-    mapToItem(const QPoint &point, QGraphicsItem *item),
-    mapToItem(const QRect &rect, QGraphicsItem *item),
-    {The Graphics View Coordinate System}
+    \sa mapToItem(), {The Graphics View Coordinate System}
 */
 QPointF QGraphicsSceneGestureEvent::mapToScene(const QPoint &point) const
 {
@@ -1826,13 +1831,10 @@ QPointF QGraphicsSceneGestureEvent::mapToScene(const QPoint &point) const
     Maps the rectangular \a rect, which is in a view coordinate system, to
     scene coordinate system, and returns the mapped coordinate.
 
-    \a Point is in coordinate system of the widget that received
+    A \a rect is in coordinate system of the widget that received
     gesture event.
 
-    \sa mapToScene(const QPoint &rect),
-    mapToItem(const QPoint &point, QGraphicsItem *item),
-    mapToItem(const QRect &rect, QGraphicsItem *item),
-    {The Graphics View Coordinate System}
+    \sa mapToItem(), {The Graphics View Coordinate System}
 */
 QPolygonF QGraphicsSceneGestureEvent::mapToScene(const QRect &rect) const
 {
@@ -1847,9 +1849,7 @@ QPolygonF QGraphicsSceneGestureEvent::mapToScene(const QRect &rect) const
 
     If \a item is 0, this function returns the same as mapToScene().
 
-    \sa mapToScene(const QPoint &rect), mapToScene(const QRect &rect),
-    mapToItem(const QRect &, QGraphicsItem *item),
-    {The Graphics View Coordinate System}
+    \sa mapToScene(), {The Graphics View Coordinate System}
 */
 QPointF QGraphicsSceneGestureEvent::mapToItem(const QPoint &point, QGraphicsItem *item) const
 {
@@ -1863,14 +1863,12 @@ QPointF QGraphicsSceneGestureEvent::mapToItem(const QPoint &point, QGraphicsItem
 }
 
 /*!
-    Maps the point \a point, which is in a view coordinate system, to
+    Maps the rectangualar \a rect, which is in a view coordinate system, to
     item's \a item coordinate system, and returns the mapped coordinate.
 
     If \a item is 0, this function returns the same as mapToScene().
 
-    \sa mapToScene(const QPoint &rect), mapToScene(const QRect &rect),
-    mapToItem(const QPoint &point, QGraphicsItem *item),
-    {The Graphics View Coordinate System}
+    \sa mapToScene(), {The Graphics View Coordinate System}
 */
 QPolygonF QGraphicsSceneGestureEvent::mapToItem(const QRect &rect, QGraphicsItem *item) const
 {
@@ -1883,6 +1881,9 @@ QPolygonF QGraphicsSceneGestureEvent::mapToItem(const QRect &rect, QGraphicsItem
     return QPolygonF();
 }
 
+/*!
+    Set a list of gesture objects containing extended information about \a gestures.
+*/
 void QGraphicsSceneGestureEvent::setGestures(const QList<QSharedPointer<QGesture> > &gestures)
 {
     foreach(const QSharedPointer<QGesture> &g, gestures)