Improve/extend QgsSymbol docs

python/core/auto_generated/symbology/qgssymbol.sip.in

@@ -15,6 +15,10 @@ typedef QList<QgsSymbolLayer *> QgsSymbolLayerList;
 
 class QgsSymbol
 {
+%Docstring
+
+Abstract base class for all rendered symbols.
+%End
 
 %TypeHeaderCode
 #include "qgssymbol.h"
@@ -56,15 +60,20 @@ class QgsSymbol
 
     static QgsSymbol *defaultSymbol( QgsWkbTypes::GeometryType geomType ) /Factory/;
 %Docstring
-Returns new default symbol for specified geometry type
+Returns a new default symbol for the specified geometry type.
+
+The caller takes ownership of the returned object.
 %End
 
     SymbolType type() const;
+%Docstring
+Returns the symbol's type.
+%End
 
 
     QgsSymbolLayerList symbolLayers();
 %Docstring
-Returns list of symbol layers contained in the symbol.
+Returns the list of symbol layers contained in the symbol.
 
 :return: symbol layers list
 
@@ -77,7 +86,7 @@ Returns list of symbol layers contained in the symbol.
 
     QgsSymbolLayer *symbolLayer( int layer );
 %Docstring
-Returns a specific symbol layers contained in the symbol.
+Returns a specific symbol layer contained in the symbol.
 
 :param layer: layer number
 
@@ -92,7 +101,7 @@ Returns a specific symbol layers contained in the symbol.
 
     int symbolLayerCount() const;
 %Docstring
-Returns total number of symbol layers contained in the symbol.
+Returns the total number of symbol layers contained in the symbol.
 
 :return: count of symbol layers
 
@@ -105,8 +114,8 @@ Returns total number of symbol layers contained in the symbol.
 
     bool insertSymbolLayer( int index, QgsSymbolLayer *layer /Transfer/ );
 %Docstring
-Insert symbol layer to specified index
+Inserts a symbol ``layer`` to specified ``index``.
-Ownership will be transferred.
+Ownership of ``layer`` is transferred to the symbol.
 
 :param index: The index at which the layer should be added
 :param layer: The symbol layer to add
@@ -116,23 +125,22 @@ Ownership will be transferred.
 
     bool appendSymbolLayer( QgsSymbolLayer *layer /Transfer/ );
 %Docstring
-Append symbol layer at the end of the list
+Appends a symbol ``layer`` at the end of the current symbol layer list.
-Ownership will be transferred.
+Ownership of ``layer`` is transferred to the symbol.
 
-:param layer: The layer to add
+:return: true if the layer was successfully added, false if the layer is not compatible with the
-
+         symbol's type().
-:return: True if the layer is added, False if the layer is bad
 %End
 
     bool deleteSymbolLayer( int index );
 %Docstring
-delete symbol layer at specified index
+Removes and deletes the symbol layer at the specified ``index``.
 %End
 
     QgsSymbolLayer *takeSymbolLayer( int index ) /TransferBack/;
 %Docstring
-Remove symbol layer from the list and return pointer to it.
+Removes a symbol layer from the list and returns a pointer to it.
-Ownership is handed to the caller.
+Ownership of the layer is handed to the caller.
 
 :param index: The index of the layer to remove
 
@@ -141,7 +149,11 @@ Ownership is handed to the caller.
 
     bool changeSymbolLayer( int index, QgsSymbolLayer *layer /Transfer/ );
 %Docstring
-delete layer at specified index and set a new one
+Deletes the current layer at the specified ``index`` and replaces it with ``layer``.
+Ownership of ``layer`` is transferred to the symbol.
+
+Returns false if ``layer`` is not compatible with the symbol's type(), or
+true if the layer was successfully replaced.
 %End
 
     void startRender( QgsRenderContext &context, const QgsFields &fields = QgsFields() );
@@ -168,24 +180,63 @@ Ends the rendering process. This should be called after rendering all desired fe
 %End
 
     void setColor( const QColor &color );
+%Docstring
+Sets the ``color`` for the symbol.
+
+Calling this method sets the color for each individual symbol layer contained
+within the symbol to ``color``.
+
+Locked symbol layers are skipped and are left unchanged.
+
+.. seealso:: :py:func:`color`
+%End
+
     QColor color() const;
+%Docstring
+Returns the symbol's color.
+
+For multi-layer symbols, this method returns the color of the first unlocked symbol
+layer.
+
+.. seealso:: :py:func:`setColor`
+%End
 
     void drawPreviewIcon( QPainter *painter, QSize size, QgsRenderContext *customContext = 0 );
 %Docstring
-Draw icon of the symbol that occupyies area given by size using the painter.
+Draws an icon of the symbol that occupies an area given by ``size`` using the specified ``painter``.
-Optionally custom context may be given in order to get rendering of symbols that use map units right.
+
+Optionally a custom render context may be given in order to ensure that the preview icon exactly
+matches the settings from that context.
 
 .. versionadded:: 2.6
+
+.. seealso:: :py:func:`exportImage`
+
+.. seealso:: :py:func:`asImage`
 %End
 
     void exportImage( const QString &path, const QString &format, QSize size );
 %Docstring
-export symbol as image format. PNG and SVG supported
+Export the symbol as an image format, to the specified ``path`` and with the given ``size``.
+
+If ``format`` is "SVG" then an SVG file will be created, otherwise a raster image of the
+specified format will be created.
+
+.. seealso:: :py:func:`asImage`
+
+.. seealso:: :py:func:`drawPreviewIcon`
 %End
 
     QImage asImage( QSize size, QgsRenderContext *customContext = 0 );
 %Docstring
-Generate symbol as image
+Returns an image of the symbol at the specified ``size``.
+
+Optionally a custom render context may be given in order to ensure that the preview icon exactly
+matches the settings from that context.
+
+.. seealso:: :py:func:`exportImage`
+
+.. seealso:: :py:func:`drawPreviewIcon`
 %End
 
     QImage bigSymbolPreviewImage( QgsExpressionContext *expressionContext = 0 );
@@ -194,18 +245,28 @@ Returns a large (roughly 100x100 pixel) preview image for the symbol.
 
 :param expressionContext: optional expression context, for evaluation of
                           data defined symbol properties
+
+.. seealso:: :py:func:`asImage`
+
+.. seealso:: :py:func:`drawPreviewIcon`
 %End
 
     QString dump() const;
+%Docstring
+Returns a string dump of the symbol's properties.
+%End
 
     virtual QgsSymbol *clone() const = 0 /Factory/;
 %Docstring
-Gets a deep copy of this symbol.
+Returns a deep copy of this symbol.
-Needs to be reimplemented by subclasses.
+
 Ownership is transferred to the caller.
 %End
 
     void toSld( QDomDocument &doc, QDomElement &element, QgsStringMap props ) const;
+%Docstring
+Converts the symbol to a SLD representation.
+%End
 
     QgsUnitTypes::RenderUnit outputUnit() const;
 %Docstring
@@ -232,7 +293,25 @@ may use it to specify the units for the line width.
 %End
 
     QgsMapUnitScale mapUnitScale() const;
+%Docstring
+Returns the map unit scale for the symbol.
+
+If the symbol consists of multiple layers, the map unit scale is only
+returned if all layers have the same scale settings. If the settings differ,
+a default constructed map unit scale is returned.
+
+.. seealso:: :py:func:`setMapUnitScale`
+%End
+
     void setMapUnitScale( const QgsMapUnitScale &scale );
+%Docstring
+Sets the map unit ``scale`` for the symbol.
+
+Calling this method sets the scale for all symbol layers contained within the
+symbol.
+
+.. seealso:: :py:func:`mapUnitScale`
+%End
 
     qreal opacity() const;
 %Docstring

src/core/symbology/qgssymbol.h

@@ -57,6 +57,8 @@ typedef QList<QgsSymbolLayer *> QgsSymbolLayerList;
 /**
  * \ingroup core
  * \class QgsSymbol
+ *
+ * Abstract base class for all rendered symbols.
  */
 class CORE_EXPORT QgsSymbol
 {
@@ -107,15 +109,22 @@ class CORE_EXPORT QgsSymbol
 
     virtual ~QgsSymbol();
 
-    //! Returns new default symbol for specified geometry type
+    /**
+     * Returns a new default symbol for the specified geometry type.
+     *
+     * The caller takes ownership of the returned object.
+     */
     static QgsSymbol *defaultSymbol( QgsWkbTypes::GeometryType geomType ) SIP_FACTORY;
 
+    /**
+     * Returns the symbol's type.
+     */
     SymbolType type() const { return mType; }
 
     // symbol layers handling
 
     /**
-     * Returns list of symbol layers contained in the symbol.
+     * Returns the list of symbol layers contained in the symbol.
      * \returns symbol layers list
      * \see symbolLayer
      * \see symbolLayerCount
@@ -124,7 +133,7 @@ class CORE_EXPORT QgsSymbol
     QgsSymbolLayerList symbolLayers() { return mLayers; }
 
     /**
-     * Returns a specific symbol layers contained in the symbol.
+     * Returns a specific symbol layer contained in the symbol.
      * \param layer layer number
      * \returns corresponding symbol layer
      * \see symbolLayers
@@ -134,7 +143,7 @@ class CORE_EXPORT QgsSymbol
     QgsSymbolLayer *symbolLayer( int layer );
 
     /**
-     * Returns total number of symbol layers contained in the symbol.
+     * Returns the total number of symbol layers contained in the symbol.
      * \returns count of symbol layers
      * \see symbolLayers
      * \see symbolLayer
@@ -143,8 +152,8 @@ class CORE_EXPORT QgsSymbol
     int symbolLayerCount() const { return mLayers.count(); }
 
     /**
-     * Insert symbol layer to specified index
+     * Inserts a symbol \a layer to specified \a index.
-     * Ownership will be transferred.
+     * Ownership of \a layer is transferred to the symbol.
      * \param index The index at which the layer should be added
      * \param layer The symbol layer to add
      * \returns True if the layer is added, False if the index or the layer is bad
@@ -152,25 +161,33 @@ class CORE_EXPORT QgsSymbol
     bool insertSymbolLayer( int index, QgsSymbolLayer *layer SIP_TRANSFER );
 
     /**
-     * Append symbol layer at the end of the list
+     * Appends a symbol \a layer at the end of the current symbol layer list.
-     * Ownership will be transferred.
+     * Ownership of \a layer is transferred to the symbol.
-     * \param layer The layer to add
+     * \returns true if the layer was successfully added, false if the layer is not compatible with the
-     * \returns True if the layer is added, False if the layer is bad
+     * symbol's type().
      */
     bool appendSymbolLayer( QgsSymbolLayer *layer SIP_TRANSFER );
 
-    //! delete symbol layer at specified index
+    /**
+     * Removes and deletes the symbol layer at the specified \a index.
+     */
     bool deleteSymbolLayer( int index );
 
     /**
-     * Remove symbol layer from the list and return pointer to it.
+     * Removes a symbol layer from the list and returns a pointer to it.
-     * Ownership is handed to the caller.
+     * Ownership of the layer is handed to the caller.
      * \param index The index of the layer to remove
      * \returns A pointer to the removed layer
      */
     QgsSymbolLayer *takeSymbolLayer( int index ) SIP_TRANSFERBACK;
 
-    //! delete layer at specified index and set a new one
+    /**
+     * Deletes the current layer at the specified \a index and replaces it with \a layer.
+     * Ownership of \a layer is transferred to the symbol.
+     *
+     * Returns false if \a layer is not compatible with the symbol's type(), or
+     * true if the layer was successfully replaced.
+     */
     bool changeSymbolLayer( int index, QgsSymbolLayer *layer SIP_TRANSFER );
 
     /**
@@ -192,38 +209,87 @@ class CORE_EXPORT QgsSymbol
      */
     void stopRender( QgsRenderContext &context );
 
+    /**
+     * Sets the \a color for the symbol.
+     *
+     * Calling this method sets the color for each individual symbol layer contained
+     * within the symbol to \a color.
+     *
+     * Locked symbol layers are skipped and are left unchanged.
+     *
+     * \see color()
+     */
     void setColor( const QColor &color );
+
+    /**
+     * Returns the symbol's color.
+     *
+     * For multi-layer symbols, this method returns the color of the first unlocked symbol
+     * layer.
+     *
+     * \see setColor()
+     */
     QColor color() const;
 
     /**
-     * Draw icon of the symbol that occupyies area given by size using the painter.
+     * Draws an icon of the symbol that occupies an area given by \a size using the specified \a painter.
-     * Optionally custom context may be given in order to get rendering of symbols that use map units right.
+     *
+     * Optionally a custom render context may be given in order to ensure that the preview icon exactly
+     * matches the settings from that context.
+     *
      * \since QGIS 2.6
+     * \see exportImage()
+     * \see asImage()
      */
     void drawPreviewIcon( QPainter *painter, QSize size, QgsRenderContext *customContext = nullptr );
 
-    //! export symbol as image format. PNG and SVG supported
+    /**
+     * Export the symbol as an image format, to the specified \a path and with the given \a size.
+     *
+     * If \a format is "SVG" then an SVG file will be created, otherwise a raster image of the
+     * specified format will be created.
+     *
+     * \see asImage()
+     * \see drawPreviewIcon()
+     */
     void exportImage( const QString &path, const QString &format, QSize size );
 
-    //! Generate symbol as image
+    /**
+     * Returns an image of the symbol at the specified \a size.
+     *
+     * Optionally a custom render context may be given in order to ensure that the preview icon exactly
+     * matches the settings from that context.
+     *
+     * \see exportImage()
+     * \see drawPreviewIcon()
+     */
     QImage asImage( QSize size, QgsRenderContext *customContext = nullptr );
 
     /**
      * Returns a large (roughly 100x100 pixel) preview image for the symbol.
      * \param expressionContext optional expression context, for evaluation of
      * data defined symbol properties
+     *
+     * \see asImage()
+     * \see drawPreviewIcon()
      */
     QImage bigSymbolPreviewImage( QgsExpressionContext *expressionContext = nullptr );
 
+    /**
+     * Returns a string dump of the symbol's properties.
+     */
     QString dump() const;
 
     /**
-     * Gets a deep copy of this symbol.
+     * Returns a deep copy of this symbol.
-     * Needs to be reimplemented by subclasses.
+     *
      * Ownership is transferred to the caller.
      */
     virtual QgsSymbol *clone() const = 0 SIP_FACTORY;
 
+    /**
+     * Converts the symbol to a SLD representation.
+     */
     void toSld( QDomDocument &doc, QDomElement &element, QgsStringMap props ) const;
 
     /**
@@ -246,7 +312,25 @@ class CORE_EXPORT QgsSymbol
      */
     void setOutputUnit( QgsUnitTypes::RenderUnit unit );
 
+    /**
+     * Returns the map unit scale for the symbol.
+     *
+     * If the symbol consists of multiple layers, the map unit scale is only
+     * returned if all layers have the same scale settings. If the settings differ,
+     * a default constructed map unit scale is returned.
+     *
+     * \see setMapUnitScale()
+     */
     QgsMapUnitScale mapUnitScale() const;
+
+    /**
+     * Sets the map unit \a scale for the symbol.
+     *
+     * Calling this method sets the scale for all symbol layers contained within the
+     * symbol.
+     *
+     * \see mapUnitScale()
+     */
     void setMapUnitScale( const QgsMapUnitScale &scale );
 
     /**