Merge pull request #8733 from m-kuhn/geometry_check_api_docs

Add geometry check to API documentation

Author: m-kuhn

doc/CMakeLists.txt

@@ -96,6 +96,7 @@ IF(WITH_APIDOC)
       ${CMAKE_SOURCE_DIR}/src/analysis/processing
       ${CMAKE_SOURCE_DIR}/src/analysis/raster
       ${CMAKE_SOURCE_DIR}/src/analysis/vector
+      ${CMAKE_SOURCE_DIR}/src/analysis/vector/geometry_checker
       ${CMAKE_SOURCE_DIR}/src/3d
       ${CMAKE_SOURCE_DIR}/src/3d/chunks
       ${CMAKE_SOURCE_DIR}/src/3d/symbols

python/analysis/auto_generated/vector/geometry_checker/qgsfeaturepool.sip.in

@@ -27,12 +27,16 @@ A feature pool is based on a vector layer and caches features.
 #include "qgsfeaturepool.h"
 %End
   public:
+
     QgsFeaturePool( QgsVectorLayer *layer );
+%Docstring
+Creates a new feature pool for ``layer``.
+%End
     virtual ~QgsFeaturePool();
 
     bool getFeature( QgsFeatureId id, QgsFeature &feature, QgsFeedback *feedback = 0 );
 %Docstring
-Retrieve the feature with the specified ``id`` into ``feature``.
+Retrieves the feature with the specified ``id`` into ``feature``.
 It will be retrieved from the cache or from the underlying layer if unavailable.
 If the feature is neither available from the cache nor from the layer it will return false.
 If ``feedback`` is specified, the call may return if the feedback is canceled.
@@ -55,7 +59,7 @@ Implementations will remove the feature from the layer or from the data provider
 
     QgsVectorLayer *layer() const;
 %Docstring
-Get a pointer to the underlying layer.
+Gets a pointer to the underlying layer.
 May return a ``None`` if the layer has been deleted.
 This must only be called from the main thread.
 %End

python/analysis/auto_generated/vector/geometry_checker/qgsgeometrycheck.sip.in

@@ -164,6 +164,10 @@ Returns the context
   protected:
 
 
+
+
+
+
 };
 
 /************************************************************************

python/analysis/auto_generated/vector/geometry_checker/qgsgeometrycheckerror.sip.in

@@ -27,34 +27,120 @@ This represents an error reported by a geometry check.
 #include "qgsgeometrycheckerror.h"
 %End
   public:
-    enum Status { StatusPending, StatusFixFailed, StatusFixed, StatusObsolete };
-    enum ValueType { ValueLength, ValueArea, ValueOther };
+
+    enum Status
+    {
+      StatusPending,
+      StatusFixFailed,
+      StatusFixed,
+      StatusObsolete
+    };
+
+    enum ValueType
+    {
+      ValueLength,
+      ValueArea,
+      ValueOther
+    };
 
     QgsGeometryCheckError( const QgsGeometryCheck *check,
                            const QgsGeometryCheckerUtils::LayerFeature &layerFeature,
                            const QgsPointXY &errorLocation,
                            QgsVertexId vidx = QgsVertexId(),
                            const QVariant &value = QVariant(),
                            ValueType valueType = ValueOther );
+%Docstring
+Create a new geometry check error with the parent ``check`` and for the
+``layerFeature`` pair at the ``errorLocation``. Optionally the vertex can be
+specified via ``vixd`` and a ``value`` with its ``value`` Type for
+additional information.
+%End
 
     virtual ~QgsGeometryCheckError();
 
 
     const QgsGeometryCheck *check() const;
+%Docstring
+The geometry check that created this error.
+%End
+
     const QString &layerId() const;
+%Docstring
+The id of the layer on which this error has been detected.
+%End
+
     QgsFeatureId featureId() const;
+%Docstring
+The id of the feature on which this error has been detected.
+%End
+
     QgsGeometry geometry() const;
+%Docstring
+The geometry of the error in map units.
+%End
+
     virtual QgsRectangle affectedAreaBBox() const;
+%Docstring
+The bounding box of the affected area of the error.
+%End
+
     virtual QString description() const;
+%Docstring
+The error description. By default the description of the parent check
+will be returned.
+%End
+
     const QgsPointXY &location() const;
+%Docstring
+The location of the error in map units.
+%End
+
     QVariant value() const;
+%Docstring
+An additional value for the error.
+Lengths and areas are provided in map units.
+
+.. seealso:: :py:func:`valueType`
+%End
+
     ValueType valueType() const;
+%Docstring
+The type of the value.
+
+.. seealso:: :py:func:`value`
+%End
+
     const QgsVertexId &vidx() const;
+%Docstring
+The id of the affected vertex. May be valid or not, depending on the
+check.
+%End
+
     Status status() const;
+%Docstring
+The status of the error.
+%End
+
     QString resolutionMessage() const;
+%Docstring
+A message with details, how the error has been resolved.
+%End
+
     void setFixed( int method );
+%Docstring
+Set the status to fixed and specify the ``method`` that has been used to
+fix the error.
+%End
+
     void setFixFailed( const QString &reason );
+%Docstring
+Set the error status to failed and specify the ``reason`` for failure.
+%End
+
     void setObsolete();
+%Docstring
+Set the error status to obsolete.
+%End
 
     virtual bool isEqual( QgsGeometryCheckError *other ) const;
 %Docstring
@@ -71,12 +157,13 @@ If this returns true, it can be used to update existing errors after re-checking
 
     virtual void update( const QgsGeometryCheckError *other );
 %Docstring
-Update this error with the information from \other.
+Update this error with the information from ``other``.
 Will be used to update existing errors whenever they are re-checked.
 %End
 
 
   protected:
+
     QgsGeometryCheckError( const QgsGeometryCheck *check,
                            const QString &layerId,
                            QgsFeatureId featureId,
@@ -85,6 +172,14 @@ Will be used to update existing errors whenever they are re-checked.
                            QgsVertexId vidx = QgsVertexId(),
                            const QVariant &value = QVariant(),
                            ValueType valueType = ValueOther );
+%Docstring
+Create a new geometry check error with the parent ``check`` and for the
+layer with ``layerId`` and ``featureId``.
+The ``geometry`` of the error and the ``errorLocation`` need to be
+specified in map coordinates.
+Optionally the vertex can be specified via ``vixd`` and a ``value`` with
+its ``value`` Type for additional information.
+%End
 
 
 };

python/analysis/auto_generated/vector/geometry_checker/qgsgeometrycheckerutils.sip.in

@@ -10,7 +10,6 @@
 
 
 
-
 class QgsGeometryCheckerUtils
 {
 %Docstring
@@ -28,8 +27,16 @@ Contains utilities required for geometry checks.
 #include "qgsgeometrycheckerutils.h"
 %End
   public:
+
     class LayerFeature
 {
+%Docstring
+
+A layer feature combination to uniquely identify and access a feature in
+a set of layers.
+
+.. versionadded:: 3.4
+%End
 
 %TypeHeaderCode
 #include "qgsgeometrycheckerutils.h"
@@ -62,7 +69,11 @@ Returns the geometry of this feature.
 If useMapCrs was specified, it will already be reprojected into the
 CRS specified in the context specified in the constructor.
 %End
+
         QString id() const;
+%Docstring
+Returns a combination of the layerId and the feature id.
+%End
         bool operator==( const QgsGeometryCheckerUtils::LayerFeature &other ) const;
         bool operator!=( const QgsGeometryCheckerUtils::LayerFeature &other ) const;
 
@@ -75,6 +86,12 @@ Returns if the geometry is reprojected to the map CRS or not.
 
     class LayerFeatures
 {
+%Docstring
+
+Contains a set of layers and feature ids in those layers to pass to a geometry check.
+
+.. versionadded:: 3.4
+%End
 
 %TypeHeaderCode
 #include "qgsgeometrycheckerutils.h"

python/analysis/auto_generated/vector/geometry_checker/qgsgeometrycheckfactory.sip.in

@@ -34,7 +34,7 @@ A factory for geometry checks.
 
     virtual QgsGeometryCheck *createGeometryCheck( const QgsGeometryCheckContext *context, const QVariantMap &configuration ) const = 0 /Factory/;
 %Docstring
-Create a new geometry check with ``context`` and ``configuration``.
+Creates a new geometry check with ``context`` and ``configuration``.
 %End
 
     virtual QString id() const = 0;
@@ -66,6 +66,13 @@ The type of this check.
 template<T>
 class QgsGeometryCheckFactoryT : QgsGeometryCheckFactory
 {
+%Docstring
+Template to create a factory for a geometry check.
+
+.. note::
+
+   Not available in Python bindings.
+%End
 
 %TypeHeaderCode
 #include "qgsgeometrycheckfactory.h"

python/analysis/auto_generated/vector/geometry_checker/qgsgeometrycheckregistry.sip.in

@@ -50,14 +50,14 @@ Ownership is transferred to the caller.
 
     QList<QgsGeometryCheckFactory *> geometryCheckFactories( QgsVectorLayer *layer,  QgsGeometryCheck::CheckType type, QgsGeometryCheck::Flags flags = 0 ) const;
 %Docstring
-Get all geometry check factories that are compatible with ``layer`` and have all of the ``flags`` set.
+Returns all geometry check factories that are compatible with ``layer`` and have all of the ``flags`` set.
 
 .. versionadded:: 3.4
 %End
 
     void registerGeometryCheck( QgsGeometryCheckFactory *checkFactory /Transfer/ );
 %Docstring
-Register a new geometry check factory.
+Registers a new geometry check factory.
 
 .. versionadded:: 3.4
 %End

python/analysis/auto_generated/vector/geometry_checker/qgssinglegeometrycheck.sip.in

@@ -28,13 +28,17 @@ An error from a QgsSingleGeometryCheck.
 #include "qgssinglegeometrycheck.h"
 %End
   public:
+
     QgsSingleGeometryCheckError( const QgsSingleGeometryCheck *check, const QgsGeometry &geometry, const QgsGeometry &errorLocation, const QgsVertexId &vertexId = QgsVertexId() );
+%Docstring
+Creates a new single geometry check error.
+%End
 
     virtual ~QgsSingleGeometryCheckError();
 
     virtual void update( const QgsSingleGeometryCheckError *other );
 %Docstring
-Update this error with the information from \other.
+Update this error with the information from ``other``.
 Will be used to update existing errors whenever they are re-checked.
 %End
 
@@ -93,7 +97,11 @@ The single error can be obtained via singleError.
 #include "qgssinglegeometrycheck.h"
 %End
   public:
+
     QgsGeometryCheckErrorSingle( QgsSingleGeometryCheckError *singleError, const QgsGeometryCheckerUtils::LayerFeature &layerFeature );
+%Docstring
+Creates a new error for a :py:class:`QgsSingleGeometryCheck`.
+%End
 
     QgsSingleGeometryCheckError *singleError() const;
 %Docstring
@@ -119,8 +127,12 @@ Subclasses need to implement the processGeometry method.
 #include "qgssinglegeometrycheck.h"
 %End
   public:
+
     QgsSingleGeometryCheck( const QgsGeometryCheckContext *context,
                             const QVariantMap &configuration );
+%Docstring
+Creates a new single geometry check.
+%End
 
      virtual void collectErrors( const QMap<QString, QgsFeaturePool *> &featurePools,
                         QList<QgsGeometryCheckError *> &errors,

src/analysis/vector/geometry_checker/qgsfeaturepool.h

@@ -39,19 +39,23 @@ class ANALYSIS_EXPORT QgsFeaturePool : public QgsFeatureSink SIP_ABSTRACT
 {
 
   public:
+
+    /**
+     * Creates a new feature pool for \a layer.
+     */
     QgsFeaturePool( QgsVectorLayer *layer );
     virtual ~QgsFeaturePool() = default;
 
     /**
-     * Retrieve the feature with the specified \a id into \a feature.
+     * Retrieves the feature with the specified \a id into \a feature.
      * It will be retrieved from the cache or from the underlying layer if unavailable.
      * If the feature is neither available from the cache nor from the layer it will return false.
      * If \a feedback is specified, the call may return if the feedback is canceled.
      */
     bool getFeature( QgsFeatureId id, QgsFeature &feature, QgsFeedback *feedback = nullptr );
 
     /**
-     * Get features for the provided \a request. No features will be fetched
+     * Gets features for the provided \a request. No features will be fetched
      * from the cache and the request is sent directly to the underlying feature source.
      * Results of the request are cached in the pool and the ids of all the features
      * are returned. This can be used to warm the cache for a particular area of interest
@@ -81,22 +85,22 @@ class ANALYSIS_EXPORT QgsFeaturePool : public QgsFeatureSink SIP_ABSTRACT
     QgsFeatureIds allFeatureIds() const SIP_SKIP;
 
     /**
-     * Get all feature ids in the bounding box \a rect. It will use a spatial index to
+     * Gets all feature ids in the bounding box \a rect. It will use a spatial index to
      * determine the ids.
      *
      * \note not available in Python bindings
      */
     QgsFeatureIds getIntersects( const QgsRectangle &rect ) const SIP_SKIP;
 
     /**
-     * Get a pointer to the underlying layer.
+     * Gets a pointer to the underlying layer.
      * May return a ``nullptr`` if the layer has been deleted.
      * This must only be called from the main thread.
      */
     QgsVectorLayer *layer() const;
 
     /**
-     * Get a QPointer to the underlying layer.
+     * Gets a QPointer to the underlying layer.
      * Note that access to any methods of the object
      * will need to be done on the main thread and
      * the pointer will need to be checked for validity
@@ -142,7 +146,7 @@ class ANALYSIS_EXPORT QgsFeaturePool : public QgsFeatureSink SIP_ABSTRACT
     void removeFeature( const QgsFeatureId featureId );
 
     /**
-     * Set all the feature ids governed by this feature pool.
+     * Sets all the feature ids governed by this feature pool.
      * Should be called by subclasses constructor and whenever
      * they insert a new feature.
      *