Dox cleanup

qgis · Aug 5, 2020 · 96cf240 · 96cf240
1 parent c523063
commit 96cf240
Show file tree

Hide file tree

Showing 5 changed files with 169 additions and 22 deletions.
diff --git a/python/core/auto_generated/annotations/qgsannotationitem.sip.in b/python/core/auto_generated/annotations/qgsannotationitem.sip.in
@@ -13,29 +13,79 @@
 class QgsAnnotationItem
 {
 %Docstring
-*************************************************************************
+Abstract base class for annotation items which are drawn with QgsAnnotationLayers.
 
-This program is free software; you can redistribute it and/or modify  *
-it under the terms of the GNU General Public License as published by  *
-the Free Software Foundation; either version 2 of the License, or     *
-(at your option) any later version.                                   *
-
-**************************************************************************
+.. versionadded:: 3.12
 %End
 
 %TypeHeaderCode
 #include "qgsannotationitem.h"
 %End
   public:
 
-    QgsAnnotationItem *clone();
+    QgsAnnotationItem( const QgsCoordinateReferenceSystem &crs );
+
+
+    virtual ~QgsAnnotationItem();
+
+    virtual QgsAnnotationItem *clone() = 0 /Factory/;
+%Docstring
+Returns a clone of the item. Ownership is transferred to the caller.
+%End
+
+    virtual QString type() const = 0;
+%Docstring
+Returns a unique (untranslated) string identifying the type of item.
+%End
 
     QgsCoordinateReferenceSystem crs() const;
 
-    void render( QgsRenderContext &context, QgsFeedback *feedback );
+    virtual void render( QgsRenderContext &context, QgsFeedback *feedback ) = 0;
+%Docstring
+Renders the item to the specified render ``context``.
+
+The ``feedback`` argument can be used to detect render cancelations during expensive
+render operations.
+%End
+
+    virtual bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const = 0;
+%Docstring
+Writes the item's state the an XML ``element``.
+%End
 
     int zIndex() const;
 
+  private:
+    QgsAnnotationItem( const QgsAnnotationItem &other );
+};
+
+class QgsMarkerItem : QgsAnnotationItem
+{
+
+%TypeHeaderCode
+#include "qgsannotationitem.h"
+%End
+  public:
+
+    QgsMarkerItem( QgsPointXY point, const QgsCoordinateReferenceSystem &crs );
+    ~QgsMarkerItem();
+
+    virtual QString type() const;
+
+    virtual void render( QgsRenderContext &context, QgsFeedback *feedback );
+
+    virtual bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
+
+    static QgsMarkerItem *create( QDomElement &element, const QgsReadWriteContext &context ) /Factory/;
+
+    virtual QgsMarkerItem *clone() /Factory/;
+
+
+    const QgsMarkerSymbol *symbol() const;
+    void setSymbol( QgsMarkerSymbol *symbol /Transfer/ );
+
+  private:
+    QgsMarkerItem( const QgsMarkerItem &other );
 };
 
 /************************************************************************

diff --git a/python/core/auto_generated/annotations/qgsannotationlayer.sip.in b/python/core/auto_generated/annotations/qgsannotationlayer.sip.in
@@ -10,25 +10,25 @@
 
 
 
+
 class QgsAnnotationLayer : QgsMapLayer
 {
 %Docstring
-*************************************************************************
 
-This program is free software; you can redistribute it and/or modify  *
-it under the terms of the GNU General Public License as published by  *
-the Free Software Foundation; either version 2 of the License, or     *
-(at your option) any later version.                                   *
+Represents a map layer containing a set of georeferenced annotations, e.g. markers, lines, polygons or
+text items.
+
+Annotation layers store a set of QgsAnnotationItem items, which are rendered according to the item's
+z-order.
 
-**************************************************************************
+.. versionadded:: 3.12
 %End
 
 %TypeHeaderCode
 #include "qgsannotationlayer.h"
 %End
   public:
 
-
     struct LayerOptions
     {
 
@@ -43,23 +43,50 @@ Constructor for LayerOptions.
 
 
     QgsAnnotationLayer( const QString &name, const QgsAnnotationLayer::LayerOptions &options );
+%Docstring
+Constructor for a new QgsAnnotationLayer with the specified layer ``name``.
+
+The ``options`` argument specifies load-time layer options.
+%End
     ~QgsAnnotationLayer();
 
     void addItem( QgsAnnotationItem *item /Transfer/ );
+%Docstring
+Adds an ``item`` to the layer.
+
+Ownership of ``item`` is transferred to the layer.
+%End
 
 
     const QMap<QString, QgsAnnotationItem *> &items() const;
+%Docstring
+Returns a map of items contained in the layer.
+
+This map contains references to items owned by the layer, and ownership of these remains
+with the layer.
+%End
 
     void setOpacity( double opacity );
+%Docstring
+Sets the ``opacity`` for the annotation layer, where ``opacity`` is a value between 0 (totally transparent)
+and 1.0 (fully opaque).
+
+.. seealso:: :py:func:`opacity`
+%End
+
     double opacity() const;
+%Docstring
+Returns the opacity for the annotation layer, where opacity is a value between 0 (totally transparent)
+and 1.0 (fully opaque).
 
+.. seealso:: :py:func:`setOpacity`
+%End
 
-    virtual QgsAnnotationLayer *clone() const /Factory/;
 
+    virtual QgsAnnotationLayer *clone() const /Factory/;
 
     virtual QgsMapLayerRenderer *createMapRenderer( QgsRenderContext &rendererContext ) /Factory/;
 
-
     virtual QgsRectangle extent() const;
 
 

diff --git a/src/core/annotations/qgsannotationitem.h b/src/core/annotations/qgsannotationitem.h
@@ -25,25 +25,50 @@
 class QgsFeedback;
 class QgsMarkerSymbol;
 
+/**
+ * \ingroup core
+ * Abstract base class for annotation items which are drawn with QgsAnnotationLayers.
+ *
+ * \since QGIS 3.12
+ */
 class CORE_EXPORT QgsAnnotationItem
 {
   public:
 
     QgsAnnotationItem( const QgsCoordinateReferenceSystem &crs );
 
 #ifndef SIP_RUN
+    //! QgsAnnotationItem cannot be copied
     QgsAnnotationItem( const QgsAnnotationItem &other ) = delete;
+    //! QgsAnnotationItem cannot be copied
     QgsAnnotationItem &operator=( const QgsAnnotationItem &other ) = delete;
 #endif
 
     virtual ~QgsAnnotationItem() = default;
 
+    /**
+     * Returns a clone of the item. Ownership is transferred to the caller.
+     */
     virtual QgsAnnotationItem *clone() = 0 SIP_FACTORY;
+
+    /**
+     * Returns a unique (untranslated) string identifying the type of item.
+     */
     virtual QString type() const = 0;
 
     QgsCoordinateReferenceSystem crs() const { return QgsCoordinateReferenceSystem(); }
 
+    /**
+     * Renders the item to the specified render \a context.
+     *
+     * The \a feedback argument can be used to detect render cancelations during expensive
+     * render operations.
+     */
     virtual void render( QgsRenderContext &context, QgsFeedback *feedback ) = 0;
+
+    /**
+     * Writes the item's state the an XML \a element.
+     */
     virtual bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const = 0;
 
     int zIndex() const { return 0; }

diff --git a/src/core/annotations/qgsannotationlayer.h b/src/core/annotations/qgsannotationlayer.h
@@ -24,13 +24,24 @@
 
 class QgsAnnotationItem;
 
+
+/**
+ * \ingroup core
+ *
+ * Represents a map layer containing a set of georeferenced annotations, e.g. markers, lines, polygons or
+ * text items.
+ *
+ * Annotation layers store a set of QgsAnnotationItem items, which are rendered according to the item's
+ * z-order.
+ *
+ * \since QGIS 3.12
+ */
 class CORE_EXPORT QgsAnnotationLayer : public QgsMapLayer
 {
     Q_OBJECT
 
   public:
 
-
     /**
      * Setting options for loading annotation layers.
      * \since QGIS 3.12
@@ -53,24 +64,49 @@ class CORE_EXPORT QgsAnnotationLayer : public QgsMapLayer
     };
 
 
+    /**
+     * Constructor for a new QgsAnnotationLayer with the specified layer \a name.
+     *
+     * The \a options argument specifies load-time layer options.
+     */
     QgsAnnotationLayer( const QString &name, const QgsAnnotationLayer::LayerOptions &options );
     ~QgsAnnotationLayer() override;
 
+    /**
+     * Adds an \a item to the layer.
+     *
+     * Ownership of \a item is transferred to the layer.
+     */
     void addItem( QgsAnnotationItem *item SIP_TRANSFER );
 
     //KadasMapItem *takeItem( const QString &itemId );
 
+    /**
+     * Returns a map of items contained in the layer.
+     *
+     * This map contains references to items owned by the layer, and ownership of these remains
+     * with the layer.
+     */
     const QMap<QString, QgsAnnotationItem *> &items() const { return mItems; }
 
+    /**
+     * Sets the \a opacity for the annotation layer, where \a opacity is a value between 0 (totally transparent)
+     * and 1.0 (fully opaque).
+     * \see opacity()
+     */
     void setOpacity( double opacity ) { mOpacity = opacity; }
+
+    /**
+     * Returns the opacity for the annotation layer, where opacity is a value between 0 (totally transparent)
+     * and 1.0 (fully opaque).
+     * \see setOpacity()
+     */
     double opacity() const { return mOpacity; }
 
 //    QRectF margin() const;
 
     QgsAnnotationLayer *clone() const override SIP_FACTORY;
-
     QgsMapLayerRenderer *createMapRenderer( QgsRenderContext &rendererContext ) override SIP_FACTORY;
-
     QgsRectangle extent() const override;
 
 #if 0
@@ -88,7 +124,6 @@ class CORE_EXPORT QgsAnnotationLayer : public QgsMapLayer
 
   private:
     std::unique_ptr< QgsDataProvider > mDataProvider;
-
     QMap<QString, QgsAnnotationItem *> mItems;
     double mOpacity = 100;
 };

diff --git a/src/core/annotations/qgsannotationlayerrenderer.h b/src/core/annotations/qgsannotationlayerrenderer.h
@@ -26,10 +26,20 @@
 
 class QgsAnnotationLayer;
 
+/**
+ * \ingroup core
+ * Implementation of threaded rendering for annotation layers.
+ *
+ * \note not available in Python bindings
+ * \since QGIS 3.12
+ */
 class CORE_EXPORT QgsAnnotationLayerRenderer : public QgsMapLayerRenderer
 {
   public:
 
+    /**
+     * Constructor for a QgsAnnotationLayerRenderer, for the specified \a layer.
+     */
     QgsAnnotationLayerRenderer( QgsAnnotationLayer *layer, QgsRenderContext &context );
     ~QgsAnnotationLayerRenderer() override;
     QgsFeedback *feedback() const override;