Deprecate some methods, dox++

Author: nyalldawson

python/core/auto_generated/expression/qgsexpression.sip.in

@@ -144,7 +144,9 @@ Returns parser error details including location of error.
 
     const QgsExpressionNode *rootNode() const;
 %Docstring
-Returns root node of the expression. Root node is null is parsing has failed
+Returns the root node of the expression.
+
+The root node is ``None`` if parsing has failed.
 %End
 
     bool prepare( const QgsExpressionContext *context );

python/core/auto_generated/layertree/qgslayertreemodellegendnode.sip.in

@@ -165,7 +165,7 @@ Construct the node with pointer to its parent layer node
 
     QgsRenderContext *createTemporaryRenderContext() const /Factory/;
 %Docstring
-Returns a temporary context or null if legendMapViewData are not valid
+Returns a temporary context or ``None`` if legendMapViewData are not valid
 %End
 
   protected:

python/core/auto_generated/qgsmapthemecollection.sip.in

@@ -47,7 +47,7 @@ Initialize layer record with a map layer - it will be stored as a weak pointer
 
         QgsMapLayer *layer() const;
 %Docstring
-Returns map layer or null if the layer does not exist anymore
+Returns map layer or ``None`` if the layer does not exist anymore
 %End
 
         void setLayer( QgsMapLayer *layer );

python/core/auto_generated/qgssqlstatement.sip.in

@@ -54,7 +54,8 @@ successful
 
     const QgsSQLStatement::Node *rootNode() const;
 %Docstring
-Returns root node of the statement. Root node is null is parsing has failed
+Returns the root node of the statement.
+The root node is ``None`` if parsing has failed.
 %End
 
     QString statement() const;

python/core/auto_generated/qgsvectorlayerjoininfo.sip.in

@@ -34,7 +34,7 @@ Sets weak reference to the joined layer
 %End
     QgsVectorLayer *joinLayer() const;
 %Docstring
-Returns joined layer (may be null if the reference was set by layer ID and not resolved yet)
+Returns joined layer (may be ``None`` if the reference was set by layer ID and not resolved yet)
 %End
 
     void setJoinLayerId( const QString &layerId );
@@ -66,11 +66,11 @@ Returns name of the field of joined layer that will be used for join
 
     void setPrefix( const QString &prefix );
 %Docstring
-Sets prefix of fields from the joined layer. If null, joined layer's name will be used.
+Sets prefix of fields from the joined layer. If ``None``, joined layer's name will be used.
 %End
     QString prefix() const;
 %Docstring
-Returns prefix of fields from the joined layer. If null, joined layer's name will be used.
+Returns prefix of fields from the joined layer. If ``None``, joined layer's name will be used.
 %End
 
     void setUsingMemoryCache( bool enabled );

python/core/auto_generated/symbology/qgsrulebasedrenderer.sip.in

@@ -394,12 +394,12 @@ delete child rule
 
         QgsRuleBasedRenderer::Rule *takeChild( QgsRuleBasedRenderer::Rule *rule ) /TransferBack/;
 %Docstring
-take child rule out, set parent as null
+take child rule out, set parent as ``None``
 %End
 
         QgsRuleBasedRenderer::Rule *takeChildAt( int i ) /TransferBack/;
 %Docstring
-take child rule out, set parent as null
+take child rule out, set parent as ``None``
 %End
 
         QgsRuleBasedRenderer::Rule *findRuleByKey( const QString &key );

python/core/auto_generated/symbology/qgssymbol.sip.in

@@ -545,18 +545,31 @@ Sets the original value variable value for data defined symbology
 .. versionadded:: 2.12
 %End
 
-    QgsUnitTypes::RenderUnit outputUnit() const;
+ QgsUnitTypes::RenderUnit outputUnit() const /Deprecated/;
 %Docstring
-Returns the output unit for the context
+Returns the output unit for the context.
+
+.. deprecated:: No longer used and will be removed in QGIS 4.0
 %End
 
-    void setOutputUnit( QgsUnitTypes::RenderUnit u );
+ void setOutputUnit( QgsUnitTypes::RenderUnit u ) /Deprecated/;
 %Docstring
-Sets the output unit for the context
+Sets the output unit for the context.
+
+.. deprecated:: No longer used and will be removed in QGIS 4.0
 %End
 
-    QgsMapUnitScale mapUnitScale() const;
-    void setMapUnitScale( const QgsMapUnitScale &scale );
+ QgsMapUnitScale mapUnitScale() const /Deprecated/;
+%Docstring
+
+.. deprecated:: Will be removed in QGIS 4.0
+%End
+
+ void setMapUnitScale( const QgsMapUnitScale &scale ) /Deprecated/;
+%Docstring
+
+.. deprecated:: Will be removed in QGIS 4.0
+%End
 
     qreal opacity() const;
 %Docstring
@@ -577,7 +590,18 @@ Sets the ``opacity`` for the symbol.
 %End
 
     bool selected() const;
+%Docstring
+Returns ``True`` if symbols should be rendered using the selected symbol coloring and style.
+
+.. seealso:: :py:func:`setSelected`
+%End
+
     void setSelected( bool selected );
+%Docstring
+Sets whether symbols should be rendered using the selected symbol coloring and style.
+
+.. seealso:: :py:func:`selected`
+%End
 
     QgsSymbol::RenderHints renderHints() const;
 %Docstring
@@ -594,9 +618,10 @@ Sets rendering hint flags for the symbol.
 %End
 
     void setFeature( const QgsFeature *f );
+
     const QgsFeature *feature() const;
 %Docstring
-Current feature being rendered - may be null
+Returns the current feature being rendered. This may be ``None``.
 %End
 
     void setOriginalGeometryType( QgsWkbTypes::GeometryType type );
@@ -658,7 +683,12 @@ Sets the part number of current geometry
 %End
 
     double outputLineWidth( double width ) const;
-    double outputPixelSize( double size ) const;
+
+ double outputPixelSize( double size ) const /Deprecated/;
+%Docstring
+
+.. deprecated:: Use the size conversion methods in QgsRenderContext instead.
+%End
 
 
     QgsExpressionContextScope *expressionContextScope();

python/gui/auto_generated/layertree/qgslayertreeview.sip.in

@@ -243,7 +243,7 @@ instance to provide custom context menus (opened upon right-click).
 
     virtual QMenu *createContextMenu() = 0 /Factory/;
 %Docstring
-Returns a newly created menu instance (or null pointer on error)
+Returns a newly created menu instance (or ``None`` on error)
 %End
 };
 

src/3d/chunks/qgschunknode_p.h

@@ -109,15 +109,15 @@ class QgsChunkNode
     //! Returns current state of the node
     State state() const { return mState; }
 
-    //! Returns node's entry in the loader queue. Not null only when in QueuedForLoad / QueuedForUpdate state
+    //! Returns node's entry in the loader queue. Not NULLPTR only when in QueuedForLoad / QueuedForUpdate state
     QgsChunkListEntry *loaderQueueEntry() const { return mLoaderQueueEntry; }
-    //! Returns node's entry in the replacement queue. Not null only when in Loaded / QueuedForUpdate / Updating state
+    //! Returns node's entry in the replacement queue. Not NULLPTR only when in Loaded / QueuedForUpdate / Updating state
     QgsChunkListEntry *replacementQueueEntry() const { return mReplacementQueueEntry; }
-    //! Returns loader of the node. Not null only when in Loading state
+    //! Returns loader of the node. Not NULLPTR only when in Loading state
     QgsChunkLoader *loader() const { return mLoader; }
-    //! Returns associated entity (3D object). Not null only when Loaded / QueuedForUpdate / Updating state
+    //! Returns associated entity (3D object). Not NULLPTR only when Loaded / QueuedForUpdate / Updating state
     Qt3DCore::QEntity *entity() const { return mEntity; }
-    //! Returns updater job. Not null only when in Updating state
+    //! Returns updater job. Not NULLPTR only when in Updating state
     QgsChunkQueueJob *updater() const { return mUpdater; }
 
     //! Returns TRUE if all child chunks are available and thus this node could be swapped to the child nodes

src/3d/qgs3dmapscene.h

@@ -59,7 +59,7 @@ class _3D_EXPORT Qgs3DMapScene : public Qt3DCore::QEntity
 
     //! Returns camera controller
     QgsCameraController *cameraController() { return mCameraController; }
-    //! Returns terrain entity (may be temporarily null)
+    //! Returns terrain entity (may be temporarily NULLPTR)
     QgsTerrainEntity *terrainEntity() { return mTerrain; }
 
     //! Resets camera view to show the whole scene (top view)

src/app/3d/qgs3dmapcanvas.h

@@ -93,7 +93,7 @@ class Qgs3DMapCanvas : public QWidget
     //! Root entity of the 3D scene
     Qgs3DMapScene *mScene = nullptr;
 
-    //! Active map tool that receives events (if null then mouse/keyboard events are used for camera manipulation)
+    //! Active map tool that receives events (if NULLPTR then mouse/keyboard events are used for camera manipulation)
     Qgs3DMapTool *mMapTool = nullptr;
 };
 

src/app/3d/qgsvectorlayer3drendererwidget.h

@@ -42,7 +42,7 @@ class QgsSingleSymbol3DRendererWidget : public QWidget
     //! no transfer of ownership
     void setLayer( QgsVectorLayer *layer );
 
-    //! cloned symbol or null
+    //! Returns the cloned symbol or NULLPTR.
     QgsAbstract3DSymbol *symbol();
 
   signals:

src/core/expression/qgsexpression.h

@@ -228,7 +228,11 @@ class CORE_EXPORT QgsExpression
      */
     QList<QgsExpression::ParserError> parserErrors() const;
 
-    //! Returns root node of the expression. Root node is null is parsing has failed
+    /**
+     * Returns the root node of the expression.
+     *
+     * The root node is NULLPTR if parsing has failed.
+     */
     const QgsExpressionNode *rootNode() const;
 
     /**

src/core/layertree/qgslayertreemodel.h

@@ -373,7 +373,7 @@ class CORE_EXPORT QgsLayerTreeModel : public QAbstractItemModel
 #ifndef SIP_RUN
     struct LayerLegendTree
     {
-      //! Pointer to parent for each active node. Top-level nodes have null parent. Pointers are not owned.
+      //! Pointer to parent for each active node. Top-level nodes have NULLPTR parent. Pointers are not owned.
       QMap<QgsLayerTreeModelLegendNode *, QgsLayerTreeModelLegendNode *> parents;
       //! List of children for each active node. Top-level nodes are under NULLPTR key. Pointers are not owned.
       QMap<QgsLayerTreeModelLegendNode *, QList<QgsLayerTreeModelLegendNode *> > children;

src/core/layertree/qgslayertreemodellegendnode.h

@@ -163,7 +163,7 @@ class CORE_EXPORT QgsLayerTreeModelLegendNode : public QObject
     //! Construct the node with pointer to its parent layer node
     explicit QgsLayerTreeModelLegendNode( QgsLayerTreeLayer *nodeL, QObject *parent SIP_TRANSFERTHIS = nullptr );
 
-    //! Returns a temporary context or null if legendMapViewData are not valid
+    //! Returns a temporary context or NULLPTR if legendMapViewData are not valid
     QgsRenderContext *createTemporaryRenderContext() const SIP_FACTORY;
 
   protected:

src/core/layertree/qgslayertreenode.h

@@ -266,7 +266,7 @@ class CORE_EXPORT QgsLayerTreeNode : public QObject
     //! type of the node - determines which subclass is used
     NodeType mNodeType;
     bool mChecked;
-    //! pointer to the parent node - null in case of root node
+    //! pointer to the parent node - NULLPTR in case of root node
     QgsLayerTreeNode *mParent = nullptr;
     //! list of children - node is responsible for their deletion
     QList<QgsLayerTreeNode *> mChildren;

src/core/qgsmapthemecollection.h

@@ -73,7 +73,7 @@ class CORE_EXPORT QgsMapThemeCollection : public QObject
           return !( *this == other );
         }
 
-        //! Returns map layer or null if the layer does not exist anymore
+        //! Returns map layer or NULLPTR if the layer does not exist anymore
         QgsMapLayer *layer() const { return mLayer; }
 
         //! Sets the map layer for this record

src/core/qgspointlocator.h

@@ -299,7 +299,7 @@ class CORE_EXPORT QgsPointLocator : public QObject
     QHash<QgsFeatureId, QgsGeometry *> mGeoms;
     std::unique_ptr< SpatialIndex::ISpatialIndex > mRTree;
 
-    //! flag whether the layer is currently empty (i.e. mRTree is null but it is not necessary to rebuild it)
+    //! flag whether the layer is currently empty (i.e. mRTree is NULLPTR but it is not necessary to rebuild it)
     bool mIsEmptyLayer = false;
 
 

src/core/qgssqlstatement.h

@@ -68,7 +68,10 @@ class CORE_EXPORT QgsSQLStatement
 
     class Node;
 
-    //! Returns root node of the statement. Root node is null is parsing has failed
+    /**
+     * Returns the root node of the statement.
+     * The root node is NULLPTR if parsing has failed.
+     */
     const QgsSQLStatement::Node *rootNode() const;
 
     /**

src/core/qgsvectorlayerjoininfo.h

@@ -41,7 +41,7 @@ class CORE_EXPORT QgsVectorLayerJoinInfo
 
     //! Sets weak reference to the joined layer
     void setJoinLayer( QgsVectorLayer *layer ) { mJoinLayerRef = QgsVectorLayerRef( layer ); }
-    //! Returns joined layer (may be null if the reference was set by layer ID and not resolved yet)
+    //! Returns joined layer (may be NULLPTR if the reference was set by layer ID and not resolved yet)
     QgsVectorLayer *joinLayer() const { return mJoinLayerRef.get(); }
 
     //! Sets ID of the joined layer. It will need to be overwritten by setJoinLayer() to a reference to real layer
@@ -59,9 +59,9 @@ class CORE_EXPORT QgsVectorLayerJoinInfo
     //! Returns name of the field of joined layer that will be used for join
     QString joinFieldName() const { return mJoinFieldName; }
 
-    //! Sets prefix of fields from the joined layer. If null, joined layer's name will be used.
+    //! Sets prefix of fields from the joined layer. If NULLPTR, joined layer's name will be used.
     void setPrefix( const QString &prefix ) { mPrefix = prefix; }
-    //! Returns prefix of fields from the joined layer. If null, joined layer's name will be used.
+    //! Returns prefix of fields from the joined layer. If NULLPTR, joined layer's name will be used.
     QString prefix() const { return mPrefix; }
 
     //! Sets whether values from the joined layer should be cached in memory to speed up lookups
@@ -219,7 +219,7 @@ class CORE_EXPORT QgsVectorLayerJoinInfo
     //! True if the join is cached in virtual memory
     bool mMemoryCache = false;
 
-    //! Subset of fields to use from joined layer. null = use all fields
+    //! Subset of fields to use from joined layer. NULLPTR = use all fields
     std::shared_ptr<QStringList> mJoinFieldsSubset;
 
     // caching support

src/core/symbology/qgsrulebasedrenderer.h

@@ -402,10 +402,10 @@ class CORE_EXPORT QgsRuleBasedRenderer : public QgsFeatureRenderer
         //! delete child rule
         void removeChildAt( int i );
 
-        //! take child rule out, set parent as null
+        //! take child rule out, set parent as NULLPTR
         QgsRuleBasedRenderer::Rule *takeChild( QgsRuleBasedRenderer::Rule *rule ) SIP_TRANSFERBACK;
 
-        //! take child rule out, set parent as null
+        //! take child rule out, set parent as NULLPTR
         QgsRuleBasedRenderer::Rule *takeChildAt( int i ) SIP_TRANSFERBACK;
 
         /**