Merge pull request #8804 from m-kuhn/geometry_check_dox

Improved API documentation for geometry checks
qgis · Jan 7, 2019 · 0cc809b · 0cc809b
2 parents b6293f2 + 6d38a0e
commit 0cc809b
Show file tree

Hide file tree

Showing 2 changed files with 167 additions and 6 deletions.
diff --git a/python/analysis/auto_generated/vector/geometry_checker/qgsgeometrycheck.sip.in b/python/analysis/auto_generated/vector/geometry_checker/qgsgeometrycheck.sip.in
@@ -13,10 +13,90 @@
 class QgsGeometryCheck
 {
 %Docstring
-This class manages all known geometry check factories.
+This class implements a geometry check.
 
-QgsGeometryCheckRegistry is not usually directly created, but rather accessed through
-:py:func:`QgsAnalysis.geometryCheckRegistry()`
+Geometry checks run over a set of features and can detect errors like topological
+or other issues which are reported in the geometry validation panel in QGIS and
+help a user to create valid geometries.
+
+Implementing a custom geometry check consists of the following parts
+
+### Writing the check
+
+A new subclass of QgsGeometryCheck needs to be written and at least the following
+abstract methods need to be implemented:
+
+- `compatibleGeometryTypes()`
+
+A list of geometry types to which this check applies
+
+- `resolutionMethods()`
+
+A list of names for (automated) resolution methods that can be used to fix errors of this type
+
+- `description()`
+
+A description for the geometry check.
+
+- `id()`
+
+A unique id for this check.
+
+- `checkType()`
+
+One of QgsGeometryCheck.LayerCheck, QgsGeometryCheck.FeatureCheck,QgsGeometryCheck.FeatureNodeCheck
+
+- \link collectErrors() `collectErrors(featurePools, errors, messages, feedback, ids)`\endlink
+
+This method will be called to validate geometries. All geometries which should be validated are passed
+into this method with the parameter ids and should be retrieved from the available featurePools to make
+use of caching. New errors should be appended to the error list and other message strings to messages.
+The method needs to return a tuple (errors, messages).
+
+### Creating a geometry check factory
+
+A Geometry check factory manages meta information for checks. There will always be one single
+geometry check factory created per check type, but it's possible that multiple QgsGeometryCheck
+instances are created and used in parallel.
+
+A new subclass of QgsGeometryCheckFactory needs to be written and at least the following
+abstract methods need to be implemented:
+
+- \link QgsGeometryCheckFactory.createGeometryCheck() `createGeometryCheck(context, configuration)`\endlink
+
+Needs to return a new subclassed QgsGeometryCheck object that has been written in the previous step.
+
+- \link QgsGeometryCheckFactory.id() `id()\endlink
+
+A unique id for this geometry check.
+
+- \link QgsGeometryCheckFactory.description() `description()\endlink
+
+A description for this geometry check that can be presented to the user for more explanation.
+
+- \link QgsGeometryCheckFactory.isCompatible() `QgsGeometryCheckFactory.isCompatible(layer)`\endlink
+
+Returns a boolean that determines if this check is available for a given layer. This often
+checks for the geometry type of the layer.
+
+- \link QgsGeometryCheckFactory.flags() `flags()`\endlink
+
+Returns additional flags for a geometry check. If unsure return QgsGeometryCheck.AvailableInValidation.
+
+- \link QgsGeometryCheckFactory.checkType() `checkType()`\endlink
+
+Returns the type of this geometry check.
+
+### Registering the geometry check
+
+Finally the geometry check factory needs to be registered in QGIS, so the system
+is aware of the available geometry checks.
+
+.. code-block:: python
+
+     # Make sure you always keep a
+     checkFactory = MyGeometryCheckFactory()
+     QgsAnalysis.geometryCheckRegistry().registerGeometryCheck(checkFactory)
 
 .. note::
 

diff --git a/src/analysis/vector/geometry_checker/qgsgeometrycheck.h b/src/analysis/vector/geometry_checker/qgsgeometrycheck.h
@@ -33,10 +33,91 @@ class QgsFeaturePool;
 
 /**
  * \ingroup analysis
- * This class manages all known geometry check factories.
+ * This class implements a geometry check.
  *
- * QgsGeometryCheckRegistry is not usually directly created, but rather accessed through
- * QgsAnalysis::geometryCheckRegistry().
+ * Geometry checks run over a set of features and can detect errors like topological
+ * or other issues which are reported in the geometry validation panel in QGIS and
+ * help a user to create valid geometries.
+ *
+ * Implementing a custom geometry check consists of the following parts
+ *
+ * ### Writing the check
+ *
+ * A new subclass of QgsGeometryCheck needs to be written and at least the following
+ * abstract methods need to be implemented:
+ *
+ *  - `compatibleGeometryTypes()`
+ *
+ *    A list of geometry types to which this check applies
+ *
+ *  - `resolutionMethods()`
+ *
+ *    A list of names for (automated) resolution methods that can be used to fix errors of this type
+ *
+ *  - `description()`
+ *
+ *    A description for the geometry check.
+ *
+ *  - `id()`
+ *
+ *    A unique id for this check.
+ *
+ *  - `checkType()`
+ *
+ *    One of QgsGeometryCheck.LayerCheck, QgsGeometryCheck.FeatureCheck,QgsGeometryCheck.FeatureNodeCheck
+ *
+ *  - \link collectErrors() `collectErrors(featurePools, errors, messages, feedback, ids)`\endlink
+ *
+ *    This method will be called to validate geometries. All geometries which should be validated are passed
+ *    into this method with the parameter ids and should be retrieved from the available featurePools to make
+ *    use of caching. New errors should be appended to the error list and other message strings to messages.
+ *    The method needs to return a tuple (errors, messages).
+ *
+ *
+ * ### Creating a geometry check factory
+ *
+ * A Geometry check factory manages meta information for checks. There will always be one single
+ * geometry check factory created per check type, but it's possible that multiple QgsGeometryCheck
+ * instances are created and used in parallel.
+ *
+ * A new subclass of QgsGeometryCheckFactory needs to be written and at least the following
+ * abstract methods need to be implemented:
+ *
+ *  - \link QgsGeometryCheckFactory::createGeometryCheck() `createGeometryCheck(context, configuration)`\endlink
+ *
+ *    Needs to return a new subclassed QgsGeometryCheck object that has been written in the previous step.
+ *
+ *  - \link QgsGeometryCheckFactory::id() `id()\endlink
+ *
+ *    A unique id for this geometry check.
+ *
+ *  - \link QgsGeometryCheckFactory::description() `description()\endlink
+ *
+ *    A description for this geometry check that can be presented to the user for more explanation.
+ *
+ *  - \link QgsGeometryCheckFactory::isCompatible() `QgsGeometryCheckFactory::isCompatible(layer)`\endlink
+ *
+ *    Returns a boolean that determines if this check is available for a given layer. This often
+ *    checks for the geometry type of the layer.
+ *
+ *  - \link QgsGeometryCheckFactory::flags() `flags()`\endlink
+ *
+ *    Returns additional flags for a geometry check. If unsure return QgsGeometryCheck.AvailableInValidation.
+ *
+ *  - \link QgsGeometryCheckFactory::checkType() `checkType()`\endlink
+ *
+ *    Returns the type of this geometry check.
+ *
+ * ### Registering the geometry check
+ *
+ * Finally the geometry check factory needs to be registered in QGIS, so the system
+ * is aware of the available geometry checks.
+ *
+ * \code{.py}
+ * # Make sure you always keep a
+ * checkFactory = MyGeometryCheckFactory()
+ * QgsAnalysis.geometryCheckRegistry().registerGeometryCheck(checkFactory)
+ * \endcode
  *
  * \note This class is a technology preview and unstable API.
  * \since QGIS 3.4