Indentation and docs

Author: nyalldawson

src/core/qgscolorramp.h

@@ -23,6 +23,7 @@
 /** \ingroup core
  * \class QgsColorRamp
  * \brief Abstract base class for color ramps
+ * \note added in QGIS 3.0
  */
 class CORE_EXPORT QgsColorRamp
 {
@@ -60,6 +61,7 @@ class CORE_EXPORT QgsColorRamp
 /** \ingroup core
  * \class QgsGradientStop
  * \brief Represents a color stop within a QgsGradientColorRamp color ramp.
+ * \note added in QGIS 3.0
  */
 class CORE_EXPORT QgsGradientStop
 {
@@ -95,6 +97,7 @@ typedef QList<QgsGradientStop> QgsGradientStopsList;
  * \class QgsGradientColorRamp
  * \brief Gradient color ramp, which smoothly interpolates between two colors and also
  * supports optional extra color stops.
+ * \note added in QGIS 3.0
  */
 class CORE_EXPORT QgsGradientColorRamp : public QgsColorRamp
 {
@@ -108,9 +111,9 @@ class CORE_EXPORT QgsGradientColorRamp : public QgsColorRamp
      * @param stops optional list of additional color stops
      */
     QgsGradientColorRamp( const QColor& color1 = DEFAULT_GRADIENT_COLOR1,
-                                const QColor& color2 = DEFAULT_GRADIENT_COLOR2,
-                                bool discrete = false,
-                                const QgsGradientStopsList& stops = QgsGradientStopsList() );
+                          const QColor& color2 = DEFAULT_GRADIENT_COLOR2,
+                          bool discrete = false,
+                          const QgsGradientStopsList& stops = QgsGradientStopsList() );
 
     //! Creates a new QgsColorRamp from a map of properties
     static QgsColorRamp* create( const QgsStringMap& properties = QgsStringMap() );
@@ -221,26 +224,39 @@ class CORE_EXPORT QgsGradientColorRamp : public QgsColorRamp
 /** \ingroup core
  * \class QgsLimitedRandomColorRamp
  * \brief Constrained random color ramp, which returns random colors based on preset parameters.
+ * \note added in QGIS 3.0
  */
 class CORE_EXPORT QgsLimitedRandomColorRamp : public QgsColorRamp
 {
   public:
-    QgsLimitedRandomColorRamp( int count = DEFAULT_RANDOM_COUNT,
-                              int hueMin = DEFAULT_RANDOM_HUE_MIN, int hueMax = DEFAULT_RANDOM_HUE_MAX,
-                              int satMin = DEFAULT_RANDOM_SAT_MIN, int satMax = DEFAULT_RANDOM_SAT_MAX,
-                              int valMin = DEFAULT_RANDOM_VAL_MIN, int valMax = DEFAULT_RANDOM_VAL_MAX );
 
+    /** Constructor for QgsLimitedRandomColorRamp
+     * @param count number of colors in ramp
+     * @param hueMin minimum hue
+     * @param hueMax maximum hue
+     * @param satMin minimum saturation
+     * @param satMax maximum saturation
+     * @param valMin minimum color value
+     * @param valMax maximum color value
+     */
+    QgsLimitedRandomColorRamp( int count = DEFAULT_RANDOM_COUNT,
+                               int hueMin = DEFAULT_RANDOM_HUE_MIN, int hueMax = DEFAULT_RANDOM_HUE_MAX,
+                               int satMin = DEFAULT_RANDOM_SAT_MIN, int satMax = DEFAULT_RANDOM_SAT_MAX,
+                               int valMin = DEFAULT_RANDOM_VAL_MIN, int valMax = DEFAULT_RANDOM_VAL_MAX );
+
+    /** Returns a new QgsLimitedRandomColorRamp color ramp created using the properties encoded in a string
+     * map.
+     * @param properties color ramp properties
+     * @see properties()
+     */
     static QgsColorRamp* create( const QgsStringMap& properties = QgsStringMap() );
 
     virtual double value( int index ) const override;
-
     virtual QColor color( double value ) const override;
-
     virtual QString type() const override { return "random"; }
-
     virtual QgsLimitedRandomColorRamp* clone() const override;
-
     virtual QgsStringMap properties() const override;
+    int count() const override { return mCount; }
 
     /** Get a list of random colors
      * @note added in 2.4
@@ -250,22 +266,73 @@ class CORE_EXPORT QgsLimitedRandomColorRamp : public QgsColorRamp
                                        int satMax = DEFAULT_RANDOM_SAT_MAX, int satMin = DEFAULT_RANDOM_SAT_MIN,
                                        int valMax = DEFAULT_RANDOM_VAL_MAX, int valMin = DEFAULT_RANDOM_VAL_MIN );
 
+    /** Must be called after changing the properties of the color ramp
+     * to regenerate the list of random colors.
+     */
     void updateColors();
 
-    int count() const override { return mCount; }
+    /** Returns the minimum hue for generated colors
+     * @see setHueMin()
+     */
     int hueMin() const { return mHueMin; }
+
+    /** Returns the maximum hue for generated colors
+     * @see setHueMax()
+     */
     int hueMax() const { return mHueMax; }
+
+    /** Returns the minimum saturation for generated colors
+     * @see setSatMin()
+     */
     int satMin() const { return mSatMin; }
+
+    /** Returns the maximum saturation for generated colors
+     * @see setSatMax()
+     */
     int satMax() const { return mSatMax; }
+
+    /** Returns the minimum value for generated colors
+     * @see setValMin()
+     */
     int valMin() const { return mValMin; }
+
+    /** Returns the maximum value for generated colors
+     * @see setValMax()
+     */
     int valMax() const { return mValMax; }
 
+    /** Sets the number of colors contained in the ramp.
+     */
     void setCount( int val ) { mCount = val; }
+
+    /** Sets the minimum hue for generated colors
+     * @see hueMin()
+     */
     void setHueMin( int val ) { mHueMin = val; }
+
+    /** Sets the maximum hue for generated colors
+     * @see hueMax()
+     */
     void setHueMax( int val ) { mHueMax = val; }
+
+    /** Sets the minimum saturation for generated colors
+     * @see satMin()
+     */
     void setSatMin( int val ) { mSatMin = val; }
+
+    /** Sets the maximum saturation for generated colors
+     * @see satMax()
+     */
     void setSatMax( int val ) { mSatMax = val; }
+
+    /** Sets the minimum value for generated colors
+     * @see valMin()
+     */
     void setValMin( int val ) { mValMin = val; }
+
+    /** Sets the maximum value for generated colors
+     * @see valMax()
+     */
     void setValMax( int val ) { mValMax = val; }
 
   protected:
@@ -276,6 +343,9 @@ class CORE_EXPORT QgsLimitedRandomColorRamp : public QgsColorRamp
 
 /** \ingroup core
  * \class QgsRandomColorRamp
+ * \brief Totally random color ramp. Returns colors generated at random, but constrained
+ * to some hardcoded saturation and value ranges to prevent ugly color generation.
+ * \note added in QGIS 3.0
  */
 class CORE_EXPORT QgsRandomColorRamp: public QgsColorRamp
 {
@@ -316,37 +386,73 @@ class CORE_EXPORT QgsRandomColorRamp: public QgsColorRamp
 
 /** \ingroup core
  * \class QgsColorBrewerColorRamp
+ * \brief Color ramp utilising "Color Brewer" preset color schemes.
+ * \note added in QGIS 3.0
  */
 class CORE_EXPORT QgsColorBrewerColorRamp : public QgsColorRamp
 {
   public:
+
+    /** Constructor for QgsColorBrewerColorRamp
+     * @param schemeName color brewer scheme name
+     * @param colors number of colors in ramp
+     */
     QgsColorBrewerColorRamp( const QString& schemeName = DEFAULT_COLORBREWER_SCHEMENAME,
-                                   int colors = DEFAULT_COLORBREWER_COLORS );
+                             int colors = DEFAULT_COLORBREWER_COLORS );
 
+    /** Returns a new QgsColorBrewerColorRamp color ramp created using the properties encoded in a string
+     * map.
+     * @param properties color ramp properties
+     * @see properties()
+     */
     static QgsColorRamp* create( const QgsStringMap& properties = QgsStringMap() );
 
     virtual double value( int index ) const override;
-
     virtual QColor color( double value ) const override;
-
     virtual QString type() const override { return "colorbrewer"; }
-
     virtual QgsColorBrewerColorRamp* clone() const override;
-
     virtual QgsStringMap properties() const override;
+    virtual int count() const override { return mColors; }
 
+    /** Returns the name of the color brewer color scheme.
+     * @see setSchemeName()
+     */
     QString schemeName() const { return mSchemeName; }
-    virtual int count() const override { return mColors; }
+
+    /** Returns the number of colors in the ramp.
+     * @see setColors()
+     */
     int colors() const { return mColors; }
 
+    /** Sets the name of the color brewer color scheme.
+     * @param schemeName scheme name, must match a valid color brewer scheme name
+     * @see schemeName()
+     * @see listSchemeNames()
+     */
     void setSchemeName( const QString& schemeName ) { mSchemeName = schemeName; loadPalette(); }
+
+    /** Sets the number of colors in the ramp.
+     * @param colors number of colors. Must match a valid value for the scheme,
+     * which can be retrieved using listSchemeVariants()
+     * @see colors()
+     */
     void setColors( int colors ) { mColors = colors; loadPalette(); }
 
+    /** Returns a list of all valid color brewer scheme names.
+     * @see listSchemeVariants()
+     */
     static QStringList listSchemeNames();
+
+    /** Returns a list of the valid variants (numbers of colors) for a specified
+     * color brewer scheme name
+     * @param schemeName color brewer scheme name
+     * @see listSchemeNames()
+     */
     static QList<int> listSchemeVariants( const QString& schemeName );
 
   protected:
 
+    //! Generates the scheme using the current name and number of colors
     void loadPalette();
 
     QString mSchemeName;

src/core/symbology-ng/qgsfillsymbollayer.h

@@ -238,8 +238,19 @@ class CORE_EXPORT QgsGradientFillSymbolLayer : public QgsFillSymbolLayer
     GradientColorType gradientColorType() const { return mGradientColorType; }
     void setGradientColorType( GradientColorType gradientColorType ) { mGradientColorType = gradientColorType; }
 
-    /** Color ramp used for the gradient fill, only used if the gradient color type is set to ColorRamp*/
+    /** Returns the color ramp used for the gradient fill. This is only
+     * used if the gradient color type is set to ColorRamp.
+     * @see setColorRamp()
+     * @see gradientColorType()
+     */
     QgsColorRamp* colorRamp() { return mGradientRamp; }
+
+    /** Sets the color ramp used for the gradient fill. This is only
+     * used if the gradient color type is set to ColorRamp.
+     * @param ramp color ramp. Ownership is transferred.
+     * @see colorRamp()
+     * @see setGradientColorType()
+     */
     void setColorRamp( QgsColorRamp* ramp );
 
     /** Color for endpoint of gradient, only used if the gradient color type is set to SimpleTwoColor*/

src/core/symbology-ng/qgsgraduatedsymbolrenderer.h

@@ -247,6 +247,17 @@ class CORE_EXPORT QgsGraduatedSymbolRenderer : public QgsFeatureRenderer
     //! @note Added in 2.6
     void calculateLabelPrecision( bool updateRanges = true );
 
+    /** Creates a new graduated renderer.
+     * @param vlayer vector layer
+     * @param attrName attribute to classify
+     * @param classes number of classes
+     * @param mode classification mode
+     * @param symbol base symbol
+     * @param ramp color ramp for classes
+     * @param inverted set to true to invert color ramp
+     * @param legendFormat
+     * @returns new QgsGraduatedSymbolRenderer object
+     */
     static QgsGraduatedSymbolRenderer* createRenderer(
       QgsVectorLayer* vlayer,
       const QString& attrName,

src/core/symbology-ng/qgssymbollayerutils.h

@@ -138,13 +138,24 @@ class CORE_EXPORT QgsSymbolLayerUtils
      */
     static QIcon symbolLayerPreviewIcon( QgsSymbolLayer* layer, QgsUnitTypes::RenderUnit u, QSize size, const QgsMapUnitScale& scale = QgsMapUnitScale() );
 
+    /** Returns a icon preview for a color ramp.
+     * @param ramp color ramp
+     * @param size target icon size
+     * @see colorRampPreviewPixmap()
+     */
     static QIcon colorRampPreviewIcon( QgsColorRamp* ramp, QSize size );
 
+    /** Returns a pixmap preview for a color ramp.
+     * @param ramp color ramp
+     * @param size target pixmap size
+     * @see colorRampPreviewIcon()
+     */
+    static QPixmap colorRampPreviewPixmap( QgsColorRamp* ramp, QSize size );
+
     static void drawStippledBackground( QPainter* painter, QRect rect );
 
     //! @note customContext parameter added in 2.6
     static QPixmap symbolPreviewPixmap( QgsSymbol* symbol, QSize size, QgsRenderContext* customContext = nullptr );
-    static QPixmap colorRampPreviewPixmap( QgsColorRamp* ramp, QSize size );
 
     /** Returns the maximum estimated bleed for the symbol */
     static double estimateMaxSymbolBleed( QgsSymbol* symbol );
@@ -297,7 +308,20 @@ class CORE_EXPORT QgsSymbolLayerUtils
 
     static void clearSymbolMap( QgsSymbolMap& symbols );
 
+    /** Creates a color ramp from the settings encoded in an XML element
+     * @param element DOM element
+     * @returns new color ramp. Caller takes responsiblity for deleting the returned value.
+     * @see saveColorRamp()
+     */
     static QgsColorRamp* loadColorRamp( QDomElement& element );
+
+    /** Encodes a color ramp's settings to an XML element
+     * @param name name of ramp
+     * @param ramp color ramp to save
+     * @param doc XML document
+     * @returns DOM element representing state of color ramp
+     * @see loadColorRamp()
+     */
     static QDomElement saveColorRamp( const QString& name, QgsColorRamp* ramp, QDomDocument& doc );
 
     /**