From d1e2978314c7520079538cca8b39a63176f1a08a Mon Sep 17 00:00:00 2001
From: Nyall Dawson <nyall.dawson@gmail.com>
Date: Fri, 26 Oct 2018 11:05:48 +1000
Subject: [PATCH] Add warning to QgsLayerTreeLayer::layer() dox

Because the returned pointer must ALWAYS be tested before
being dereferenced
---
 .../layertree/qgslayertreelayer.sip.in        | 20 +++++++++++++++++++
 src/core/layertree/qgslayertreelayer.h        | 20 +++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/python/core/auto_generated/layertree/qgslayertreelayer.sip.in b/python/core/auto_generated/layertree/qgslayertreelayer.sip.in
index 05a0bead2e1..792f50f6418 100644
--- 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
index d3d9c45c10e..bb30ddf1b4a 100644
--- 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;