Improve docs

qgis · Sep 10, 2021 · 45b8867 · 45b8867
1 parent 24a9509
commit 45b8867
Show file tree

Hide file tree

Showing 4 changed files with 42 additions and 6 deletions.
diff --git a/python/core/auto_generated/processing/qgsprocessingalgorithm.sip.in b/python/core/auto_generated/processing/qgsprocessingalgorithm.sip.in
@@ -993,9 +993,16 @@ need to handle deletion of the returned layer.
 %Docstring
 Evaluates the parameter with matching ``name`` to an annotation layer.
 
-Annotation layers will either be taken from ``context``'s active project. Callers do not
+Annotation layers will be taken from ``context``'s active project. Callers do not
 need to handle deletion of the returned layer.
 
+.. warning::
+
+   Working with annotation layers is generally not thread safe (unless the layers are from
+   a :py:class:`QgsProject` loaded directly in a background thread). Ensure your algorithm returns the
+   QgsProcessingAlgorithm.FlagNoThreading flag or only accesses annotation layers from a :py:func:`~QgsProcessingAlgorithm.prepareAlgorithm`
+   or :py:func:`~QgsProcessingAlgorithm.postProcessAlgorithm` step.
+
 .. versionadded:: 3.22
 %End
 

diff --git a/python/core/auto_generated/processing/qgsprocessingparameters.sip.in b/python/core/auto_generated/processing/qgsprocessingparameters.sip.in
@@ -1544,19 +1544,33 @@ need to handle deletion of the returned layer.
 %Docstring
 Evaluates the parameter with matching ``definition`` to an annotation layer.
 
-Layers will either be taken from ``context``'s active project. Callers do not
+Layers will be taken from ``context``'s active project. Callers do not
 need to handle deletion of the returned layer.
 
+.. warning::
+
+   Working with annotation layers is generally not thread safe (unless the layers are from
+   a :py:class:`QgsProject` loaded directly in a background thread). Ensure your algorithm returns the
+   :py:class:`QgsProcessingAlgorithm`.FlagNoThreading flag or only accesses annotation layers from a :py:func:`~QgsProcessingParameters.prepareAlgorithm`
+   or :py:func:`~QgsProcessingParameters.postProcessAlgorithm` step.
+
 .. versionadded:: 3.22
 %End
 
     static QgsAnnotationLayer *parameterAsAnnotationLayer( const QgsProcessingParameterDefinition *definition, const QVariant &value, QgsProcessingContext &context );
 %Docstring
 Evaluates the parameter with matching ``definition`` and ``value`` to an annotation layer.
 
-Layers will either be taken from ``context``'s active project. Callers do not
+Layers will be taken from ``context``'s active project. Callers do not
 need to handle deletion of the returned layer.
 
+.. warning::
+
+   Working with annotation layers is generally not thread safe (unless the layers are from
+   a :py:class:`QgsProject` loaded directly in a background thread). Ensure your algorithm returns the
+   :py:class:`QgsProcessingAlgorithm`.FlagNoThreading flag or only accesses annotation layers from a :py:func:`~QgsProcessingParameters.prepareAlgorithm`
+   or :py:func:`~QgsProcessingParameters.postProcessAlgorithm` step.
+
 .. versionadded:: 3.22
 %End
 

diff --git a/src/core/processing/qgsprocessingalgorithm.h b/src/core/processing/qgsprocessingalgorithm.h
@@ -991,9 +991,14 @@ class CORE_EXPORT QgsProcessingAlgorithm
     /**
      * Evaluates the parameter with matching \a name to an annotation layer.
      *
-     * Annotation layers will either be taken from \a context's active project. Callers do not
+     * Annotation layers will be taken from \a context's active project. Callers do not
      * need to handle deletion of the returned layer.
      *
+     * \warning Working with annotation layers is generally not thread safe (unless the layers are from
+     * a QgsProject loaded directly in a background thread). Ensure your algorithm returns the
+     * QgsProcessingAlgorithm::FlagNoThreading flag or only accesses annotation layers from a prepareAlgorithm()
+     * or postProcessAlgorithm() step.
+     *
      * \since QGIS 3.22
      */
     QgsAnnotationLayer *parameterAsAnnotationLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;

diff --git a/src/core/processing/qgsprocessingparameters.h b/src/core/processing/qgsprocessingparameters.h
@@ -1599,19 +1599,29 @@ class CORE_EXPORT QgsProcessingParameters
     /**
      * Evaluates the parameter with matching \a definition to an annotation layer.
      *
-     * Layers will either be taken from \a context's active project. Callers do not
+     * Layers will be taken from \a context's active project. Callers do not
      * need to handle deletion of the returned layer.
      *
+     * \warning Working with annotation layers is generally not thread safe (unless the layers are from
+     * a QgsProject loaded directly in a background thread). Ensure your algorithm returns the
+     * QgsProcessingAlgorithm::FlagNoThreading flag or only accesses annotation layers from a prepareAlgorithm()
+     * or postProcessAlgorithm() step.
+     *
      * \since QGIS 3.22
      */
     static QgsAnnotationLayer *parameterAsAnnotationLayer( const QgsProcessingParameterDefinition *definition, const QVariantMap &parameters, QgsProcessingContext &context );
 
     /**
      * Evaluates the parameter with matching \a definition and \a value to an annotation layer.
      *
-     * Layers will either be taken from \a context's active project. Callers do not
+     * Layers will be taken from \a context's active project. Callers do not
      * need to handle deletion of the returned layer.
      *
+     * \warning Working with annotation layers is generally not thread safe (unless the layers are from
+     * a QgsProject loaded directly in a background thread). Ensure your algorithm returns the
+     * QgsProcessingAlgorithm::FlagNoThreading flag or only accesses annotation layers from a prepareAlgorithm()
+     * or postProcessAlgorithm() step.
+     *
      * \since QGIS 3.22
      */
     static QgsAnnotationLayer *parameterAsAnnotationLayer( const QgsProcessingParameterDefinition *definition, const QVariant &value, QgsProcessingContext &context );