[composer] Small improvements to API docs

qgis · May 23, 2014 · e8b7ca9 · e8b7ca9
1 parent 084fa89
commit e8b7ca9
Show file tree

Hide file tree

Showing 4 changed files with 126 additions and 46 deletions.
diff --git a/python/core/composer/qgsatlascomposition.sip b/python/core/composer/qgsatlascomposition.sip
@@ -51,11 +51,11 @@ public:
     void setHideCoverage( bool hide );
 
     /**Returns whether the atlas map uses a fixed scale
-     * @deprecated Use QgsComposerMap::atlasFixedScale() instead
+     * @deprecated since 2.4 Use QgsComposerMap::atlasScalingMode() instead
      */
     bool fixedScale() const /Deprecated/;
     /**Sets whether the atlas map should use a fixed scale
-     * @deprecated Use QgsComposerMap::setAtlasFixedScale( bool ) instead
+     * @deprecated since 2.4 Use QgsComposerMap::setAtlasScalingMode() instead
      */
     void setFixedScale( bool fixed ) /Deprecated/;
 
@@ -131,12 +131,19 @@ public:
     int sortKeyAttributeIndex() const /Deprecated/;
     void setSortKeyAttributeIndex( int idx ) /Deprecated/;
 
-    /** Returns the current list of predefined scales
-        @returns a vector of doubles representing predefined scales
+    /**Returns the current list of predefined scales for the atlas. This is used
+     * for maps which are set to the predefined atlas scaling mode.
+     * @returns a vector of doubles representing predefined scales
+     * @see setPredefinedScales
+     * @see QgsComposerMap::atlasScalingMode
     */
     const QVector<double>& predefinedScales() const;
-    /** Sets the predefined scales
-        @param scales a vector of doubles representing predefined scales
+
+    /**Sets the list of predefined scales for the atlas. This is used
+     * for maps which are set to the predefined atlas scaling mode.
+     * @param scales a vector of doubles representing predefined scales
+     * @see predefinedScales
+     * @see QgsComposerMap::atlasScalingMode
      */
     void setPredefinedScales( const QVector<double>& scales );
 

diff --git a/python/core/composer/qgscomposermap.sip b/python/core/composer/qgscomposermap.sip
@@ -75,13 +75,14 @@ class QgsComposerMap : QgsComposerItem
     enum AtlasScalingMode
     {
       Fixed,      /*< The current scale of the map is used for each feature of the atlas */
-      Predefined, /*< A scale is chosen from the predefined scales
+      Predefined, /*< A scale is chosen from the predefined scales. The smallest scale from
+                    the list of scales where the atlas feature is fully visible is chosen.
                     @see QgsAtlasComposition::setPredefinedScales.
-                    The smallest scale from the list of scales where the atlas feature
-                    is fully visible is chosen.
-                  */
+                    @note This mode is only valid for polygon or line atlas coverage layers
+                */
       Auto        /*< The extent is adjusted so that each feature is fully visible.
-                    A margin is applied around the center @see setAtlasMargin */
+                    A margin is applied around the center @see setAtlasMargin
+                    @note This mode is only valid for polygon or line atlas coverage layers*/
     };
 
     /** \brief Draw to paint device
@@ -403,32 +404,64 @@ class QgsComposerMap : QgsComposerItem
     */
     void sizeChangedByRotation( double& width, double& height ) /Deprecated/;
 
-    /** Returns true if the map extent is set to follow the current atlas feature */
+    /**Returns whether the map extent is set to follow the current atlas feature.
+     * @returns true if map will follow the current atlas feature.
+     * @see setAtlasDriven
+     * @see atlasScalingMode
+    */
     bool atlasDriven() const;
-    /** Set to true if the map extents should be set by the current atlas feature */
+
+    /**Sets whether the map extent will follow the current atlas feature.
+     * @param enabled set to true if the map extents should be set by the current atlas feature.
+     * @see atlasDriven
+     * @see setAtlasScalingMode
+    */
     void setAtlasDriven( bool enabled );
 
-    /** Returns true if the map uses a fixed scale when in atlas mode
-        @deprecated since 2.4 Use atlasScalingMode() instead
+    /**Returns true if the map uses a fixed scale when in atlas mode
+     * @deprecated since 2.4 Use atlasScalingMode() instead
     */
     bool atlasFixedScale() const /Deprecated/;
-    /** Set to true if the map should use a fixed scale when in atlas mode
-        @deprecated since 2.4 Use setAtlasScalingMode() instead
+
+    /**Set to true if the map should use a fixed scale when in atlas mode
+     * @deprecated since 2.4 Use setAtlasScalingMode() instead
     */
     void setAtlasFixedScale( bool fixed ) /Deprecated/;
 
-    /** Returns the current atlas scaling mode
-        @returns the current scaling mode
+    /**Returns the current atlas scaling mode. This controls how the map's extents
+     * are calculated for the current atlas feature when an atlas composition
+     * is enabled.
+     * @returns the current scaling mode
+     * @note this parameter is only used if atlasDriven() is true
+     * @see setAtlasScalingMode
+     * @see atlasDriven
     */
     AtlasScalingMode atlasScalingMode();
-    /** Sets the current atlas scaling mode
-        @param mode atlas scaling mode to set
+
+    /**Sets the current atlas scaling mode. This controls how the map's extents
+     * are calculated for the current atlas feature when an atlas composition
+     * is enabled.
+     * @param mode atlas scaling mode to set
+     * @note this parameter is only used if atlasDriven() is true
+     * @see atlasScalingMode
+     * @see atlasDriven
     */
     void setAtlasScalingMode( AtlasScalingMode mode );
 
-    /** Returns the margin size (percentage) used when the map is in atlas mode */
+    /**Returns the margin size (percentage) used when the map is in atlas mode.
+     * @returns margin size in percentage to leave around the atlas feature's extent
+     * @note this is only used if atlasScalingMode() is Auto.
+     * @see atlasScalingMode
+     * @see setAtlasMargin
+    */
     double atlasMargin() const;
-    /** Sets the margin size (percentage) used when the map is in atlas mode */
+
+    /**Sets the margin size (percentage) used when the map is in atlas mode.
+     * @param margin size in percentage to leave around the atlas feature's extent
+     * @note this is only used if atlasScalingMode() is Auto.
+     * @see atlasScalingMode
+     * @see atlasMargin
+    */
     void setAtlasMargin( double margin );
 
     /** Sets whether updates to the composer map are enabled. */

diff --git a/src/core/composer/qgsatlascomposition.h b/src/core/composer/qgsatlascomposition.h
@@ -79,12 +79,12 @@ class CORE_EXPORT QgsAtlasComposition : public QObject
     void setHideCoverage( bool hide );
 
     /**Returns whether the atlas map uses a fixed scale
-     * @deprecated Use QgsComposerMap::atlasFixedScale() instead
+     * @deprecated since 2.4 Use QgsComposerMap::atlasScalingMode() instead
      */
     Q_DECL_DEPRECATED bool fixedScale() const;
 
     /**Sets whether the atlas map should use a fixed scale
-     * @deprecated Use QgsComposerMap::setAtlasFixedScale( bool ) instead
+     * @deprecated since 2.4 Use QgsComposerMap::setAtlasScalingMode() instead
      */
     Q_DECL_DEPRECATED void setFixedScale( bool fixed );
 
@@ -160,12 +160,19 @@ class CORE_EXPORT QgsAtlasComposition : public QObject
     Q_DECL_DEPRECATED int sortKeyAttributeIndex() const;
     Q_DECL_DEPRECATED void setSortKeyAttributeIndex( int idx );
 
-    /** Returns the current list of predefined scales
-        @returns a vector of doubles representing predefined scales
+    /**Returns the current list of predefined scales for the atlas. This is used
+     * for maps which are set to the predefined atlas scaling mode.
+     * @returns a vector of doubles representing predefined scales
+     * @see setPredefinedScales
+     * @see QgsComposerMap::atlasScalingMode
     */
     const QVector<double>& predefinedScales() const { return mPredefinedScales; }
-    /** Sets the predefined scales
-        @param scales a vector of doubles representing predefined scales
+
+    /**Sets the list of predefined scales for the atlas. This is used
+     * for maps which are set to the predefined atlas scaling mode.
+     * @param scales a vector of doubles representing predefined scales
+     * @see predefinedScales
+     * @see QgsComposerMap::atlasScalingMode
      */
     void setPredefinedScales( const QVector<double>& scales );
 

diff --git a/src/core/composer/qgscomposermap.h b/src/core/composer/qgscomposermap.h
@@ -109,13 +109,14 @@ class CORE_EXPORT QgsComposerMap : public QgsComposerItem
     enum AtlasScalingMode
     {
       Fixed,      /*< The current scale of the map is used for each feature of the atlas */
-      Predefined, /*< A scale is chosen from the predefined scales
+      Predefined, /*< A scale is chosen from the predefined scales. The smallest scale from
+                    the list of scales where the atlas feature is fully visible is chosen.
                     @see QgsAtlasComposition::setPredefinedScales.
-                    The smallest scale from the list of scales where the atlas feature
-                    is fully visible is chosen.
-                  */
+                    @note This mode is only valid for polygon or line atlas coverage layers
+                */
       Auto        /*< The extent is adjusted so that each feature is fully visible.
-                    A margin is applied around the center @see setAtlasMargin */
+                    A margin is applied around the center @see setAtlasMargin
+                    @note This mode is only valid for polygon or line atlas coverage layers*/
     };
 
     /** \brief Draw to paint device
@@ -439,32 +440,64 @@ class CORE_EXPORT QgsComposerMap : public QgsComposerItem
     */
     Q_DECL_DEPRECATED void sizeChangedByRotation( double& width, double& height );
 
-    /** Returns true if the map extent is set to follow the current atlas feature */
+    /**Returns whether the map extent is set to follow the current atlas feature.
+     * @returns true if map will follow the current atlas feature.
+     * @see setAtlasDriven
+     * @see atlasScalingMode
+    */
     bool atlasDriven() const { return mAtlasDriven; }
-    /** Set to true if the map extents should be set by the current atlas feature */
+
+    /**Sets whether the map extent will follow the current atlas feature.
+     * @param enabled set to true if the map extents should be set by the current atlas feature.
+     * @see atlasDriven
+     * @see setAtlasScalingMode
+    */
     void setAtlasDriven( bool enabled ) { mAtlasDriven = enabled; }
 
-    /** Returns true if the map uses a fixed scale when in atlas mode
-        @deprecated since 2.4 Use atlasScalingMode() instead
+    /**Returns true if the map uses a fixed scale when in atlas mode
+     * @deprecated since 2.4 Use atlasScalingMode() instead
     */
     Q_DECL_DEPRECATED bool atlasFixedScale() const;
-    /** Set to true if the map should use a fixed scale when in atlas mode
-        @deprecated since 2.4 Use setAtlasScalingMode() instead
+
+    /**Set to true if the map should use a fixed scale when in atlas mode
+     * @deprecated since 2.4 Use setAtlasScalingMode() instead
     */
     Q_DECL_DEPRECATED void setAtlasFixedScale( bool fixed );
 
-    /** Returns the current atlas scaling mode
-        @returns the current scaling mode
+    /**Returns the current atlas scaling mode. This controls how the map's extents
+     * are calculated for the current atlas feature when an atlas composition
+     * is enabled.
+     * @returns the current scaling mode
+     * @note this parameter is only used if atlasDriven() is true
+     * @see setAtlasScalingMode
+     * @see atlasDriven
     */
     AtlasScalingMode atlasScalingMode() const { return mAtlasScalingMode; }
-    /** Sets the current atlas scaling mode
-        @param mode atlas scaling mode to set
+
+    /**Sets the current atlas scaling mode. This controls how the map's extents
+     * are calculated for the current atlas feature when an atlas composition
+     * is enabled.
+     * @param mode atlas scaling mode to set
+     * @note this parameter is only used if atlasDriven() is true
+     * @see atlasScalingMode
+     * @see atlasDriven
     */
     void setAtlasScalingMode( AtlasScalingMode mode ) { mAtlasScalingMode = mode; }
 
-    /** Returns the margin size (percentage) used when the map is in atlas mode */
+    /**Returns the margin size (percentage) used when the map is in atlas mode.
+     * @returns margin size in percentage to leave around the atlas feature's extent
+     * @note this is only used if atlasScalingMode() is Auto.
+     * @see atlasScalingMode
+     * @see setAtlasMargin
+    */
     double atlasMargin() const { return mAtlasMargin; }
-    /** Sets the margin size (percentage) used when the map is in atlas mode */
+
+    /**Sets the margin size (percentage) used when the map is in atlas mode.
+     * @param margin size in percentage to leave around the atlas feature's extent
+     * @note this is only used if atlasScalingMode() is Auto.
+     * @see atlasScalingMode
+     * @see atlasMargin
+    */
     void setAtlasMargin( double margin ) { mAtlasMargin = margin; }
 
     /** Sets whether updates to the composer map are enabled. */