[composer] Small improvements to api docs

Author: nyalldawson

python/core/composer/qgscomposeritem.sip

@@ -179,13 +179,30 @@ class QgsComposerItem : QObject, QGraphicsRectItem
       @param y y-position of mouse cursor (in item coordinates)*/
     virtual void zoomContent( int delta, double x, double y );
 
-    /** gets the page the item is currently on */
+    /**Gets the page the item is currently on.
+     * @returns page number for item
+     * @see pagePos
+     * @see updatePagePos
+     * @note this method was added in version 2.4
+    */
     int page() const;
 
-    /** Returns the position relative to the current page */
+    /**Returns the item's position relative to its current page.
+     * @returns position relative to the page's top left corner.
+     * @see page
+     * @see updatePagePos
+     * @note this method was added in version 2.4
+    */
     QPointF pagePos() const;
 
-    /** Updates the page relative position for the new paper size */
+    /**Moves the item so that it retains its relative position on the page
+     * when the paper size changes.
+     * @param newPageWidth new width of the page in mm
+     * @param newPageHeight new height of the page in mm
+     * @see page
+     * @see pagePos
+     * @note this method was added in version 2.4
+    */
     void updatePagePos( double newPageWidth, double newPageHeight );
 
     /**Moves the item to a new position (in canvas coordinates)*/

python/core/composer/qgscomposition.sip

@@ -48,7 +48,9 @@ class QgsComposition : QGraphicsScene
 
     ~QgsComposition();
 
-    /**Changes size of paper item*/
+    /**Changes size of paper item. Also moves all items so that they retain
+     * their same relative position to the top left corner of their current page.
+    */
     void setPaperSize( double width, double height );
 
     /**Returns height of paper item*/

src/core/composer/qgscomposeritem.h

@@ -133,13 +133,30 @@ class CORE_EXPORT QgsComposerItem: public QObject, public QGraphicsRectItem
       @param y y-position of mouse cursor (in item coordinates)*/
     virtual void zoomContent( int delta, double x, double y ) { Q_UNUSED( delta ); Q_UNUSED( x ); Q_UNUSED( y ); }
 
-    /** gets the page the item is currently on */
+    /**Gets the page the item is currently on.
+     * @returns page number for item
+     * @see pagePos
+     * @see updatePagePos
+     * @note this method was added in version 2.4
+    */
     int page() const;
 
-    /** Returns the position relative to the current page */
+    /**Returns the item's position relative to its current page.
+     * @returns position relative to the page's top left corner.
+     * @see page
+     * @see updatePagePos
+     * @note this method was added in version 2.4
+    */
     QPointF pagePos() const;
 
-    /** Updates the page relative position for the new paper size */
+    /**Moves the item so that it retains its relative position on the page
+     * when the paper size changes.
+     * @param newPageWidth new width of the page in mm
+     * @param newPageHeight new height of the page in mm
+     * @see page
+     * @see pagePos
+     * @note this method was added in version 2.4
+    */
     void updatePagePos( double newPageWidth, double newPageHeight );
 
     /**Moves the item to a new position (in canvas coordinates)*/

src/core/composer/qgscomposition.h

@@ -104,7 +104,9 @@ class CORE_EXPORT QgsComposition : public QGraphicsScene
 
     ~QgsComposition();
 
-    /**Changes size of paper item*/
+    /**Changes size of paper item. Also moves all items so that they retain
+     * their same relative position to the top left corner of their current page.
+    */
     void setPaperSize( double width, double height );
 
     /**Returns height of paper item*/