Add missing documentation for QgsCategorizedRenderer

Author: nyalldawson

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

@@ -135,6 +135,14 @@ class QgsCategorizedSymbolRenderer : QgsFeatureRenderer
   public:
 
     QgsCategorizedSymbolRenderer( const QString &attrName = QString(), const QgsCategoryList &categories = QgsCategoryList() );
+%Docstring
+Constructor for QgsCategorizedSymbolRenderer.
+
+The ``attrName`` argument specifies the layer's field name, or expression, which the categories will be matched against.
+
+A list of renderer ``categories`` can optionally be specified. If no categories are specified in the constructor, they
+can be added later by calling addCategory().
+%End
 
     virtual QgsSymbol *symbolForFeature( const QgsFeature &feature, QgsRenderContext &context ) const;
 
@@ -171,15 +179,18 @@ symbol for the renderer.
 %End
 
     const QgsCategoryList &categories() const;
+%Docstring
+Returns a list of all categories recognized by the renderer.
+%End
 
     int categoryIndexForValue( const QVariant &val );
 %Docstring
-Returns index of category with specified value (-1 if not found)
+Returns the index for the category with the specified value (or -1 if not found).
 %End
 
     int categoryIndexForLabel( const QString &val );
 %Docstring
-Returns index of category with specified label (-1 if not found or not unique)
+Returns the index of the category with the specified label (or -1 if the label was not found, or is not unique).
 
 .. versionadded:: 2.5
 %End
@@ -193,6 +204,8 @@ If ``value`` is a list, then the category will match any of the values from this
 .. seealso:: :py:func:`updateCategorySymbol`
 
 .. seealso:: :py:func:`updateCategoryLabel`
+
+.. seealso:: :py:func:`updateCategoryRenderState`
 %End
 
     bool updateCategorySymbol( int catIndex, QgsSymbol *symbol /Transfer/ );
@@ -204,6 +217,8 @@ Ownership of ``symbol`` is transferred to the renderer.
 .. seealso:: :py:func:`updateCategoryValue`
 
 .. seealso:: :py:func:`updateCategoryLabel`
+
+.. seealso:: :py:func:`updateCategoryRenderState`
 %End
 
     bool updateCategoryLabel( int catIndex, const QString &label );
@@ -216,32 +231,87 @@ legends and the layer tree.
 .. seealso:: :py:func:`updateCategoryValue`
 
 .. seealso:: :py:func:`updateCategoryLabel`
+
+.. seealso:: :py:func:`updateCategoryRenderState`
 %End
 
     bool updateCategoryRenderState( int catIndex, bool render );
 %Docstring
+Changes the render state for the category with the specified index.
+
+The render state indicates whether or not the category will be rendered,
+and is reflected in whether the category is checked with the project's layer tree.
+
+.. seealso:: :py:func:`updateCategoryValue`
+
+.. seealso:: :py:func:`updateCategorySymbol`
+
+.. seealso:: :py:func:`updateCategoryLabel`
 
 .. versionadded:: 2.5
 %End
 
     void addCategory( const QgsRendererCategory &category );
+%Docstring
+Adds a new ``category`` to the renderer.
+
+.. seealso:: :py:func:`categories`
+%End
+
     bool deleteCategory( int catIndex );
+%Docstring
+Deletes the category with the specified index from the renderer.
+
+.. seealso:: :py:func:`deleteAllCategories`
+%End
+
     void deleteAllCategories();
+%Docstring
+Deletes all existing categories from the renderer.
+
+.. seealso:: :py:func:`deleteCategory`
+%End
 
     void moveCategory( int from, int to );
 %Docstring
-Moves the category at index position from to index position to.
+Moves an existing category at index position from to index position to.
 %End
 
     void sortByValue( Qt::SortOrder order = Qt::AscendingOrder );
+%Docstring
+Sorts the existing categories by their value.
+
+.. seealso:: :py:func:`sortByLabel`
+%End
+
     void sortByLabel( Qt::SortOrder order = Qt::AscendingOrder );
+%Docstring
+Sorts the existing categories by their label.
+
+.. seealso:: :py:func:`sortByValue`
+%End
 
     QString classAttribute() const;
+%Docstring
+Returns the class attribute for the renderer, which is the field name
+or expression string from the layer which will be matched against the
+renderer categories.
+
+.. seealso:: :py:func:`setClassAttribute`
+%End
+
     void setClassAttribute( const QString &attr );
+%Docstring
+Sets the class attribute for the renderer, which is the field name
+or expression string from the layer which will be matched against the
+renderer categories.
+
+.. seealso:: :py:func:`classAttribute`
+%End
 
     static QgsFeatureRenderer *create( QDomElement &element, const QgsReadWriteContext &context ) /Factory/;
 %Docstring
-create renderer from XML element
+Creates a categorized renderer from an XML ``element``.
 %End
 
     virtual QDomElement save( QDomDocument &doc, const QgsReadWriteContext &context );

src/core/symbology/qgscategorizedsymbolrenderer.h

@@ -149,6 +149,14 @@ class CORE_EXPORT QgsCategorizedSymbolRenderer : public QgsFeatureRenderer
 {
   public:
 
+    /**
+     * Constructor for QgsCategorizedSymbolRenderer.
+     *
+     * The \a attrName argument specifies the layer's field name, or expression, which the categories will be matched against.
+     *
+     * A list of renderer \a categories can optionally be specified. If no categories are specified in the constructor, they
+     * can be added later by calling addCategory().
+     */
     QgsCategorizedSymbolRenderer( const QString &attrName = QString(), const QgsCategoryList &categories = QgsCategoryList() );
 
     QgsSymbol *symbolForFeature( const QgsFeature &feature, QgsRenderContext &context ) const override;
@@ -172,13 +180,18 @@ class CORE_EXPORT QgsCategorizedSymbolRenderer : public QgsFeatureRenderer
      */
     void updateSymbols( QgsSymbol *sym );
 
+    /**
+     * Returns a list of all categories recognized by the renderer.
+     */
     const QgsCategoryList &categories() const { return mCategories; }
 
-    //! Returns index of category with specified value (-1 if not found)
+    /**
+     * Returns the index for the category with the specified value (or -1 if not found).
+     */
     int categoryIndexForValue( const QVariant &val );
 
     /**
-     * Returns index of category with specified label (-1 if not found or not unique)
+     * Returns the index of the category with the specified label (or -1 if the label was not found, or is not unique).
      * \since QGIS 2.5
      */
     int categoryIndexForLabel( const QString &val );
@@ -190,6 +203,7 @@ class CORE_EXPORT QgsCategorizedSymbolRenderer : public QgsFeatureRenderer
      *
      * \see updateCategorySymbol()
      * \see updateCategoryLabel()
+     * \see updateCategoryRenderState()
      */
     bool updateCategoryValue( int catIndex, const QVariant &value );
 
@@ -200,6 +214,7 @@ class CORE_EXPORT QgsCategorizedSymbolRenderer : public QgsFeatureRenderer
      *
      * \see updateCategoryValue()
      * \see updateCategoryLabel()
+     * \see updateCategoryRenderState()
      */
     bool updateCategorySymbol( int catIndex, QgsSymbol *symbol SIP_TRANSFER );
 
@@ -211,26 +226,85 @@ class CORE_EXPORT QgsCategorizedSymbolRenderer : public QgsFeatureRenderer
      *
      * \see updateCategoryValue()
      * \see updateCategoryLabel()
+     * \see updateCategoryRenderState()
      */
     bool updateCategoryLabel( int catIndex, const QString &label );
 
-    //! \since QGIS 2.5
+    /**
+     * Changes the render state for the category with the specified index.
+     *
+     * The render state indicates whether or not the category will be rendered,
+     * and is reflected in whether the category is checked with the project's layer tree.
+     *
+     * \see updateCategoryValue()
+     * \see updateCategorySymbol()
+     * \see updateCategoryLabel()
+     *
+     * \since QGIS 2.5
+     */
     bool updateCategoryRenderState( int catIndex, bool render );
 
+    /**
+     * Adds a new \a category to the renderer.
+     *
+     * \see categories()
+     */
     void addCategory( const QgsRendererCategory &category );
+
+    /**
+     * Deletes the category with the specified index from the renderer.
+     *
+     * \see deleteAllCategories()
+     */
     bool deleteCategory( int catIndex );
+
+    /**
+     * Deletes all existing categories from the renderer.
+     *
+     * \see deleteCategory()
+     */
     void deleteAllCategories();
 
-    //! Moves the category at index position from to index position to.
+    /**
+     * Moves an existing category at index position from to index position to.
+     */
     void moveCategory( int from, int to );
 
+    /**
+     * Sorts the existing categories by their value.
+     *
+     * \see sortByLabel()
+     */
     void sortByValue( Qt::SortOrder order = Qt::AscendingOrder );
+
+    /**
+     * Sorts the existing categories by their label.
+     *
+     * \see sortByValue()
+     */
     void sortByLabel( Qt::SortOrder order = Qt::AscendingOrder );
 
+    /**
+     * Returns the class attribute for the renderer, which is the field name
+     * or expression string from the layer which will be matched against the
+     * renderer categories.
+     *
+     * \see setClassAttribute()
+     */
     QString classAttribute() const { return mAttrName; }
+
+    /**
+     * Sets the class attribute for the renderer, which is the field name
+     * or expression string from the layer which will be matched against the
+     * renderer categories.
+     *
+     * \see classAttribute()
+     */
     void setClassAttribute( const QString &attr ) { mAttrName = attr; }
 
-    //! create renderer from XML element
+    /**
+     * Creates a categorized renderer from an XML \a element.
+     */
     static QgsFeatureRenderer *create( QDomElement &element, const QgsReadWriteContext &context ) SIP_FACTORY;
 
     QDomElement save( QDomDocument &doc, const QgsReadWriteContext &context ) override;