Improve QgsRasterPipe docs

qgis · Jun 23, 2021 · e2b7f07 · e2b7f07
1 parent 9fd1ddf
commit e2b7f07
Show file tree

Hide file tree

Showing 3 changed files with 194 additions and 42 deletions.
diff --git a/python/core/auto_generated/raster/qgsrasterpipe.sip.in b/python/core/auto_generated/raster/qgsrasterpipe.sip.in
@@ -14,13 +14,14 @@
 class QgsRasterPipe
 {
 %Docstring(signature="appended")
-Base class for processing modules.
+Contains a pipeline of raster interfaces for sequential raster processing.
 %End
 
 %TypeHeaderCode
 #include "qgsrasterpipe.h"
 %End
   public:
+
     enum Role
     {
       UnknownRole,
@@ -35,7 +36,7 @@ Base class for processing modules.
 
     QgsRasterPipe();
 %Docstring
-Constructor for QgsRasterPipe.
+Constructor for an empty QgsRasterPipe.
 %End
 
 
@@ -44,8 +45,12 @@ Constructor for QgsRasterPipe.
 
     bool insert( int idx, QgsRasterInterface *interface /Transfer/ );
 %Docstring
-Try to insert interface at specified index and connect
+Attempts to insert interface at specified index and connect
 if connection would fail, the interface is not inserted and ``False`` is returned
+
+.. seealso:: :py:func:`set`
+
+.. seealso:: :py:func:`replace`
 %End
 %MethodCode
     sipRes = sipCpp->insert( a0, a1 );
@@ -60,51 +65,115 @@ if connection would fail, the interface is not inserted and ``False`` is returne
 
     bool replace( int idx, QgsRasterInterface *interface /Transfer/ );
 %Docstring
-Try to replace interface at specified index and connect
-if connection would fail, the interface is not inserted and ``False`` is returned
+Attempts to replace the interface at specified index and reconnect the pipe.
+
+If the connection would fail, the interface is not inserted and ``False`` is returned.
+
+.. seealso:: :py:func:`insert`
+
+.. seealso:: :py:func:`set`
 %End
 
     bool set( QgsRasterInterface *interface /Transfer/ );
 %Docstring
-Insert a new known interface in default place or replace interface of the same
-role if it already exists. Known interfaces are: :py:class:`QgsRasterDataProvider`,
-:py:class:`QgsRasterRenderer`, :py:class:`QgsRasterResampleFilter`, :py:class:`QgsRasterProjector` and their
-subclasses. For unknown interfaces it mus be explicitly specified position
-where it should be inserted using :py:func:`~QgsRasterPipe.insert` method.
+Inserts a new known interface in default place or replace interface of the same
+role if it already exists.
+
+Known interfaces are:
+
+- :py:class:`QgsRasterDataProvider`,
+- :py:class:`QgsRasterRenderer`
+- :py:class:`QgsRasterResampleFilter`
+- :py:class:`QgsRasterProjector`
+- :py:class:`QgsHueSaturationFilter`
+- :py:class:`QgsBrightnessContrastFilter`
+
+(and their subclasses).
+
+For other interfaces the position of the interface in the pipe must be explicitly
+specified using the :py:func:`~QgsRasterPipe.insert` method.
+
+.. seealso:: :py:func:`insert`
+
+.. seealso:: :py:func:`replace`
 %End
 
     bool remove( int idx );
 %Docstring
-Remove and delete interface at given index if possible
+Removes and deletes the interface at given index (if possible).
+
+Returns ``True`` if the interface was successfully removed.
 %End
 
     bool remove( QgsRasterInterface *interface );
 %Docstring
-Remove and delete interface from pipe if possible
+Removes and deletes interface from pipe (if possible).
+
+Returns ``True`` if the interface was successfully removed.
 %End
 
     int size() const;
+%Docstring
+Returns the size of the pipe (the number of interfaces contained in the pipe).
+%End
+
     QgsRasterInterface *at( int idx ) const;
+%Docstring
+Returns the interface at the specified index.
+%End
+
     QgsRasterInterface *last() const;
+%Docstring
+Returns last interface in the pipe.
+%End
 
     bool setOn( int idx, bool on );
 %Docstring
-Set interface at index on/off
-Returns ``True`` on success
+Set whether the interface at the specified index is enabled.
+
+Returns ``True`` on success.
 %End
 
     bool canSetOn( int idx, bool on );
 %Docstring
-Test if interface at index may be switched on/off
+Returns ``True`` if the interface at the specified index may be switched on or off.
 %End
 
+
     QgsRasterDataProvider *provider() const;
+%Docstring
+Returns the data provider interface, or ``None`` if no data provider is present in the pipe.
+%End
+
     QgsRasterRenderer *renderer() const;
+%Docstring
+Returns the raster renderer interface, or ``None`` if no raster renderer is present in the pipe.
+%End
+
     QgsRasterResampleFilter *resampleFilter() const;
+%Docstring
+Returns the resample filter interface, or ``None`` if no resample filter is present in the pipe.
+%End
+
     QgsBrightnessContrastFilter *brightnessFilter() const;
+%Docstring
+Returns the brightness filter interface, or ``None`` if no brightness filter is present in the pipe.
+%End
+
     QgsHueSaturationFilter *hueSaturationFilter() const;
+%Docstring
+Returns the hue/saturation interface, or ``None`` if no hue/saturation filter is present in the pipe.
+%End
+
     QgsRasterProjector *projector() const;
+%Docstring
+Returns the projector interface, or ``None`` if no projector is present in the pipe.
+%End
+
     QgsRasterNuller *nuller() const;
+%Docstring
+Returns the raster nuller interface, or ``None`` if no raster nuller is present in the pipe.
+%End
 
     enum class ResamplingStage
     {
@@ -116,18 +185,22 @@ Test if interface at index may be switched on/off
 
     void setResamplingStage( ResamplingStage stage );
 %Docstring
-Select which stage of the pipe should apply resampling.
+Sets which stage of the pipe should apply resampling.
 
 Provider resampling is only supported if provider sets
 ProviderHintCanPerformProviderResampling in :py:func:`~QgsRasterPipe.providerCapabilities`.
 
+.. seealso:: :py:func:`resamplingStage`
+
 .. versionadded:: 3.16
 %End
 
     ResamplingStage resamplingStage() const;
 %Docstring
 Returns which stage of the pipe should apply resampling
 
+.. seealso:: :py:func:`setResamplingStage`
+
 .. versionadded:: 3.16
 %End
 

diff --git a/src/core/raster/qgsrasterpipe.cpp b/src/core/raster/qgsrasterpipe.cpp
@@ -269,7 +269,8 @@ bool QgsRasterPipe::remove( int idx )
 {
   QgsDebugMsgLevel( QStringLiteral( "remove at %1" ).arg( idx ), 4 );
 
-  if ( !checkBounds( idx ) ) return false;
+  if ( !checkBounds( idx ) )
+    return false;
 
   // make a copy of pipe to test connection, we test the connections
   // of the whole pipe, because the types and band numbers may change