Improve docs for single symbol renderer, add missing SIP_FACTORY

qgis · May 25, 2018 · 99b6194 · 99b6194
1 parent 43928d8
commit 99b6194
Show file tree

Hide file tree

Showing 3 changed files with 72 additions and 14 deletions.
diff --git a/python/core/auto_generated/symbology/qgssinglesymbolrenderer.sip.in b/python/core/auto_generated/symbology/qgssinglesymbolrenderer.sip.in
@@ -16,6 +16,12 @@ class QgsSingleSymbolRenderer : QgsFeatureRenderer
   public:
 
     QgsSingleSymbolRenderer( QgsSymbol *symbol /Transfer/ );
+%Docstring
+Constructor for QgsSingleSymbolRenderer.
+
+The same ``symbol`` will be used to render every feature. Ownership
+of ``symbol`` is transferred to the renderer.
+%End
 
     virtual QgsSymbol *symbolForFeature( const QgsFeature &feature, QgsRenderContext &context ) const;
 
@@ -29,7 +35,19 @@ class QgsSingleSymbolRenderer : QgsFeatureRenderer
 
 
     QgsSymbol *symbol() const;
+%Docstring
+Returns the symbol which will be rendered for every feature.
+
+.. seealso:: :py:func:`setSymbol`
+%End
+
     void setSymbol( QgsSymbol *s /Transfer/ );
+%Docstring
+Sets the symbol which will be rendered for every feature. Ownership
+of the symbol is transferred to the renderer.
+
+.. seealso:: :py:func:`symbol`
+%End
 
     virtual QString dump() const;
 
@@ -39,16 +57,27 @@ class QgsSingleSymbolRenderer : QgsFeatureRenderer
 
     virtual void toSld( QDomDocument &doc, QDomElement &element, const QgsStringMap &props = QgsStringMap() ) const;
 
-    static QgsFeatureRenderer *createFromSld( QDomElement &element, QgsWkbTypes::GeometryType geomType );
+
+    static QgsFeatureRenderer *createFromSld( QDomElement &element, QgsWkbTypes::GeometryType geomType ) /Factory/;
+%Docstring
+Creates a new single symbol renderer from an SLD ``element``.
+
+The geometry type for features to be rendered must be specified via the ``geomType`` argument.
+
+The caller takes ownership of the returned renderer.
+%End
 
     virtual QgsFeatureRenderer::Capabilities capabilities();
     virtual QgsSymbolList symbols( QgsRenderContext &context ) const;
 
 
     static QgsFeatureRenderer *create( QDomElement &element, const QgsReadWriteContext &context ) /Factory/;
 %Docstring
-create renderer from XML element
+Creates a new single symbol renderer from an XML ``element``, using the supplied read/write ``context``.
+
+The caller takes ownership of the returned renderer.
 %End
+
     virtual QDomElement save( QDomDocument &doc, const QgsReadWriteContext &context );
 
     virtual QgsLegendSymbolList legendSymbolItems() const;
@@ -60,9 +89,9 @@ create renderer from XML element
 
     static QgsSingleSymbolRenderer *convertFromRenderer( const QgsFeatureRenderer *renderer ) /Factory/;
 %Docstring
-creates a QgsSingleSymbolRenderer from an existing renderer.
+Creates a new single symbol renderer from an existing ``renderer``.
 
-:return: a new renderer if the conversion was possible, otherwise 0.
+:return: a new renderer if the conversion was possible, otherwise None.
 
 .. versionadded:: 2.5
 %End

diff --git a/src/core/symbology/qgssinglesymbolrenderer.cpp b/src/core/symbology/qgssinglesymbolrenderer.cpp
@@ -234,28 +234,28 @@ QgsFeatureRenderer *QgsSingleSymbolRenderer::createFromSld( QDomElement &element
     return nullptr;
 
   // now create the symbol
-  QgsSymbol *symbol = nullptr;
+  std::unique_ptr< QgsSymbol > symbol;
   switch ( geomType )
   {
     case QgsWkbTypes::LineGeometry:
-      symbol = new QgsLineSymbol( layers );
+      symbol = qgis::make_unique< QgsLineSymbol >( layers );
       break;
 
     case QgsWkbTypes::PolygonGeometry:
-      symbol = new QgsFillSymbol( layers );
+      symbol = qgis::make_unique< QgsFillSymbol >( layers );
       break;
 
     case QgsWkbTypes::PointGeometry:
-      symbol = new QgsMarkerSymbol( layers );
+      symbol = qgis::make_unique< QgsMarkerSymbol >( layers );
       break;
 
     default:
-      QgsDebugMsg( QString( "invalid geometry type: found %1" ).arg( geomType ) );
+      QgsDebugMsg( QStringLiteral( "invalid geometry type: found %1" ).arg( geomType ) );
       return nullptr;
   }
 
   // and finally return the new renderer
-  return new QgsSingleSymbolRenderer( symbol );
+  return new QgsSingleSymbolRenderer( symbol.release() );
 }
 
 QDomElement QgsSingleSymbolRenderer::save( QDomDocument &doc, const QgsReadWriteContext &context )

diff --git a/src/core/symbology/qgssinglesymbolrenderer.h b/src/core/symbology/qgssinglesymbolrenderer.h
@@ -30,6 +30,12 @@ class CORE_EXPORT QgsSingleSymbolRenderer : public QgsFeatureRenderer
 {
   public:
 
+    /**
+     * Constructor for QgsSingleSymbolRenderer.
+     *
+     * The same \a symbol will be used to render every feature. Ownership
+     * of \a symbol is transferred to the renderer.
+     */
     QgsSingleSymbolRenderer( QgsSymbol *symbol SIP_TRANSFER );
 
     QgsSymbol *symbolForFeature( const QgsFeature &feature, QgsRenderContext &context ) const override;
@@ -38,29 +44,52 @@ class CORE_EXPORT QgsSingleSymbolRenderer : public QgsFeatureRenderer
     void stopRender( QgsRenderContext &context ) override;
     QSet<QString> usedAttributes( const QgsRenderContext &context ) const override;
 
+    /**
+     * Returns the symbol which will be rendered for every feature.
+     * \see setSymbol()
+     */
     QgsSymbol *symbol() const;
+
+    /**
+     * Sets the symbol which will be rendered for every feature. Ownership
+     * of the symbol is transferred to the renderer.
+     * \see symbol()
+     */
     void setSymbol( QgsSymbol *s SIP_TRANSFER );
 
     QString dump() const override;
 
     QgsSingleSymbolRenderer *clone() const override SIP_FACTORY;
 
     void toSld( QDomDocument &doc, QDomElement &element, const QgsStringMap &props = QgsStringMap() ) const override;
-    static QgsFeatureRenderer *createFromSld( QDomElement &element, QgsWkbTypes::GeometryType geomType );
+
+    /**
+     * Creates a new single symbol renderer from an SLD \a element.
+     *
+     * The geometry type for features to be rendered must be specified via the \a geomType argument.
+     *
+     * The caller takes ownership of the returned renderer.
+     */
+    static QgsFeatureRenderer *createFromSld( QDomElement &element, QgsWkbTypes::GeometryType geomType ) SIP_FACTORY;
 
     QgsFeatureRenderer::Capabilities capabilities() override { return SymbolLevels; }
     QgsSymbolList symbols( QgsRenderContext &context ) const override;
 
-    //! create renderer from XML element
+    /**
+     * Creates a new single symbol renderer from an XML \a element, using the supplied read/write \a context.
+     *
+     * The caller takes ownership of the returned renderer.
+     */
     static QgsFeatureRenderer *create( QDomElement &element, const QgsReadWriteContext &context ) SIP_FACTORY;
+
     QDomElement save( QDomDocument &doc, const QgsReadWriteContext &context ) override;
     QgsLegendSymbolList legendSymbolItems() const override;
     QSet< QString > legendKeysForFeature( const QgsFeature &feature, QgsRenderContext &context ) const override;
     void setLegendSymbolItem( const QString &key, QgsSymbol *symbol SIP_TRANSFER ) override;
 
     /**
-     * creates a QgsSingleSymbolRenderer from an existing renderer.
-     * \returns a new renderer if the conversion was possible, otherwise 0.
+     * Creates a new single symbol renderer from an existing \a renderer.
+     * \returns a new renderer if the conversion was possible, otherwise nullptr.
      * \since QGIS 2.5
      */
     static QgsSingleSymbolRenderer *convertFromRenderer( const QgsFeatureRenderer *renderer ) SIP_FACTORY;