Deprecate some methods, dox++

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;
+ QgsMapUnitScale mapUnitScale() const /Deprecated/;
-    void setMapUnitScale( const QgsMapUnitScale &scale );
+%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;
 
         /**

src/core/symbology/qgssymbol.h

@@ -585,14 +585,27 @@ class CORE_EXPORT QgsSymbolRenderContext
      */
     void setOriginalValueVariable( const QVariant &value );
 
-    //! Returns the output unit for the context
+    /**
-    QgsUnitTypes::RenderUnit outputUnit() const { return mOutputUnit; }
+     * Returns the output unit for the context.
+     * \deprecated No longer used and will be removed in QGIS 4.0
+     */
+    Q_DECL_DEPRECATED QgsUnitTypes::RenderUnit outputUnit() const SIP_DEPRECATED { return mOutputUnit; }
 
-    //! Sets the output unit for the context
+    /**
-    void setOutputUnit( QgsUnitTypes::RenderUnit u ) { mOutputUnit = u; }
+     * Sets the output unit for the context.
+     * \deprecated No longer used and will be removed in QGIS 4.0
+     */
+    Q_DECL_DEPRECATED void setOutputUnit( QgsUnitTypes::RenderUnit u ) SIP_DEPRECATED { mOutputUnit = u; }
 
-    QgsMapUnitScale mapUnitScale() const { return mMapUnitScale; }
+    /**
-    void setMapUnitScale( const QgsMapUnitScale &scale ) { mMapUnitScale = scale; }
+     * \deprecated Will be removed in QGIS 4.0
+     */
+    Q_DECL_DEPRECATED QgsMapUnitScale mapUnitScale() const SIP_DEPRECATED { return mMapUnitScale; }
+
+    /**
+     * \deprecated Will be removed in QGIS 4.0
+     */
+    Q_DECL_DEPRECATED void setMapUnitScale( const QgsMapUnitScale &scale ) SIP_DEPRECATED { mMapUnitScale = scale; }
 
     /**
      * Returns the opacity for the symbol.
@@ -608,7 +621,16 @@ class CORE_EXPORT QgsSymbolRenderContext
      */
     void setOpacity( qreal opacity ) { mOpacity = opacity; }
 
+    /**
+     * Returns TRUE if symbols should be rendered using the selected symbol coloring and style.
+     * \see setSelected()
+     */
     bool selected() const { return mSelected; }
+
+    /**
+     * Sets whether symbols should be rendered using the selected symbol coloring and style.
+     * \see selected()
+     */
     void setSelected( bool selected ) { mSelected = selected; }
 
     /**
@@ -624,7 +646,10 @@ class CORE_EXPORT QgsSymbolRenderContext
     void setRenderHints( QgsSymbol::RenderHints hints ) { mRenderHints = hints; }
 
     void setFeature( const QgsFeature *f ) { mFeature = f; }
-    //! Current feature being rendered - may be null
+
+    /**
+     * Returns the current feature being rendered. This may be NULLPTR.
+     */
     const QgsFeature *feature() const { return mFeature; }
 
     /**
@@ -677,7 +702,11 @@ class CORE_EXPORT QgsSymbolRenderContext
     void setGeometryPartNum( int num ) { mGeometryPartNum = num; }
 
     double outputLineWidth( double width ) const;
-    double outputPixelSize( double size ) const;
+
+    /**
+     * \deprecated Use the size conversion methods in QgsRenderContext instead.
+     */
+    Q_DECL_DEPRECATED double outputPixelSize( double size ) const SIP_DEPRECATED;
 
     // workaround for sip 4.7. Don't use assignment - will fail with assertion error
     QgsSymbolRenderContext &operator=( const QgsSymbolRenderContext & );

src/gui/layertree/qgslayertreeview.h

@@ -244,7 +244,7 @@ class GUI_EXPORT QgsLayerTreeViewMenuProvider
   public:
     virtual ~QgsLayerTreeViewMenuProvider() = default;
 
-    //! Returns a newly created menu instance (or null pointer on error)
+    //! Returns a newly created menu instance (or NULLPTR on error)
     virtual QMenu *createContextMenu() = 0 SIP_FACTORY;
 };
 

src/gui/qgsconfigureshortcutsdialog.h

@@ -72,10 +72,10 @@ class GUI_EXPORT QgsConfigureShortcutsDialog : public QDialog, private Ui::QgsCo
     //! Returns the currently selected shortcut object (QAction or QShortcut)
     QObject *currentObject();
 
-    //! Returns the currently selected action, or null if no action selected
+    //! Returns the currently selected action, or NULLPTR if no action selected
     QAction *currentAction();
 
-    //! Returns the currently selected QShortcut, or null if no shortcut selected
+    //! Returns the currently selected QShortcut, or NULLPTR if no shortcut selected
     QShortcut *currentShortcut();
 
     void setGettingShortcut( bool getting );