Add warning to QgsLayerTreeLayer::layer() dox

Because the returned pointer must ALWAYS be tested before being dereferenced
qgis · Oct 26, 2018 · d1e2978 · d1e2978
1 parent 6944240
commit d1e2978
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 0 deletions.
diff --git a/python/core/auto_generated/layertree/qgslayertreelayer.sip.in b/python/core/auto_generated/layertree/qgslayertreelayer.sip.in
@@ -39,14 +39,32 @@ Constructor for QgsLayerTreeLayer using weak references to layer ID, ``name``, p
 %End
 
     QString layerId() const;
+%Docstring
+Returns the ID for the map layer associated with this node.
+
+.. seealso:: :py:func:`layer`
+%End
 
     QgsMapLayer *layer() const;
+%Docstring
+Returns the map layer associated with this node.
+
+.. warning::
+
+   This can be (and often is!) a None, e.g. in the case of a layer node representing a layer
+   which has not yet been fully loaded into a project, or a layer node representing a layer
+   with an invalid data source. The returned pointer must ALWAYS be checked to avoid dereferencing a None.
+
+.. seealso:: :py:func:`layerId`
+%End
 
     virtual QString name() const;
 
 %Docstring
 Returns the layer's name.
 
+.. seealso:: :py:func:`setName`
+
 .. versionadded:: 3.0
 %End
 
@@ -55,6 +73,8 @@ Returns the layer's name.
 %Docstring
 Sets the layer's name.
 
+.. seealso:: :py:func:`name`
+
 .. versionadded:: 3.0
 %End
 

diff --git a/src/core/layertree/qgslayertreelayer.h b/src/core/layertree/qgslayertreelayer.h
@@ -54,18 +54,38 @@ class CORE_EXPORT QgsLayerTreeLayer : public QgsLayerTreeNode
      */
     explicit QgsLayerTreeLayer( const QString &layerId, const QString &name = QString(), const QString &source = QString(), const QString &provider = QString() );
 
+    /**
+     * Returns the ID for the map layer associated with this node.
+     *
+     * \see layer()
+     */
     QString layerId() const { return mRef.layerId; }
 
+    /**
+     * Returns the map layer associated with this node.
+     *
+     * \warning This can be (and often is!) a nullptr, e.g. in the case of a layer node representing a layer
+     * which has not yet been fully loaded into a project, or a layer node representing a layer
+     * with an invalid data source. The returned pointer must ALWAYS be checked to avoid dereferencing a nullptr.
+     *
+     * \see layerId()
+     */
     QgsMapLayer *layer() const { return mRef.get(); }
 
     /**
      * Returns the layer's name.
+     *
+     * \see setName()
+     *
      * \since QGIS 3.0
      */
     QString name() const override;
 
     /**
      * Sets the layer's name.
+     *
+     * \see name()
+     *
      * \since QGIS 3.0
      */
     void setName( const QString &n ) override;