Update API docs

src/core/layertree/qgslayertreemodel.cpp

@@ -33,6 +33,27 @@
 #include "qgsvectorlayer.h"
 
 
+/** In order to support embedded widgets in layer tree view, the model
+ * generates one placeholder legend node for each embedded widget.
+ * The placeholder will be replaced by an embedded widget in QgsLayerTreeView
+ */
+class EmbeddedWidgetLegendNode : public QgsLayerTreeModelLegendNode
+{
+  public:
+    EmbeddedWidgetLegendNode( QgsLayerTreeLayer* nodeL )
+        : QgsLayerTreeModelLegendNode( nodeL )
+    {
+    }
+
+    virtual QVariant data( int role ) const override
+    {
+      Q_UNUSED( role );
+      return QVariant();
+    }
+};
+
+
+
 QgsLayerTreeModel::QgsLayerTreeModel( QgsLayerTreeGroup* rootNode, QObject *parent )
     : QAbstractItemModel( parent )
     , mRootNode( rootNode )
@@ -1149,21 +1170,6 @@ void QgsLayerTreeModel::removeLegendFromLayer( QgsLayerTreeLayer* nodeLayer )
   }
 }
 
-class EmbeddedWidgetLegendNode : public QgsLayerTreeModelLegendNode
-{
-  public:
-    EmbeddedWidgetLegendNode( QgsLayerTreeLayer* nodeL )
-        : QgsLayerTreeModelLegendNode( nodeL )
-    {
-    }
-
-    virtual QVariant data( int role ) const override
-    {
-      Q_UNUSED( role );
-      return QVariant();
-    }
-
-};
 
 void QgsLayerTreeModel::addLegendToLayer( QgsLayerTreeLayer* nodeL )
 {
@@ -1186,6 +1192,7 @@ void QgsLayerTreeModel::addLegendToLayer( QgsLayerTreeLayer* nodeL )
 
   if ( testFlag( UseEmbeddedWidgets ) )
   {
+    // generate placeholder legend nodes that will be replaced by widgets in QgsLayerTreeView
     int widgetsCount = ml->customProperty( "embeddedWidgets/count", 0 ).toInt();
     while ( widgetsCount > 0 )
     {

src/core/layertree/qgslayertreemodel.h

@@ -277,6 +277,7 @@ class CORE_EXPORT QgsLayerTreeModel : public QAbstractItemModel
     QVariant legendNodeData( QgsLayerTreeModelLegendNode* node, int role ) const;
     Qt::ItemFlags legendNodeFlags( QgsLayerTreeModelLegendNode* node ) const;
     bool legendEmbeddedInParent( QgsLayerTreeLayer* nodeLayer ) const;
+    /** Return legend node that may be embbeded in parent (i.e. its icon will be used for layer's icon). */
     QgsLayerTreeModelLegendNode* legendNodeEmbeddedInParent( QgsLayerTreeLayer* nodeLayer ) const;
     QIcon legendIconEmbeddedInParent( QgsLayerTreeLayer* nodeLayer ) const;
     void legendCleanup();

src/gui/layertree/qgslayertreeembeddedconfigwidget.h

@@ -5,14 +5,21 @@
 
 class QgsMapLayer;
 
+/** \ingroup gui
+ * \class QgsLayerTreeEmbeddedConfigWidget
+ * A widget to configure layer tree embedded widgets for a particular map layer.
+ * @note introduced in QGIS 2.16
+ */
 class GUI_EXPORT QgsLayerTreeEmbeddedConfigWidget : public QWidget, protected Ui::QgsLayerTreeEmbeddedConfigWidget
 {
     Q_OBJECT
   public:
     QgsLayerTreeEmbeddedConfigWidget( QWidget* parent = nullptr );
 
+    //! Initialize widget with a map layer
     void setLayer( QgsMapLayer* layer );
 
+    //! Store changes made in the widget to the layer
     void applyToLayer();
 
   private slots:

src/gui/layertree/qgslayertreeembeddedwidgetregistry.h

@@ -22,7 +22,13 @@
 
 class QgsMapLayer;
 
-/** Provider interface to be implemented */
+/** \ingroup gui
+ * \class QgsLayerTreeEmbeddedWidgetProvider
+ * Provider interface to be implemented in order to introduce new kinds of embedded widgets for use in layer tree.
+ * Embedded widgets are assigned per individual map layers and they are shown before any legend entries.
+ * @see QgsLayerTreeEmbeddedWidgetRegistry
+ * @note introduced in QGIS 2.16
+ */
 class GUI_EXPORT QgsLayerTreeEmbeddedWidgetProvider
 {
   public:
@@ -42,7 +48,15 @@ class GUI_EXPORT QgsLayerTreeEmbeddedWidgetProvider
 
 };
 
-/** Singleton registry */
+/** \ingroup gui
+ * \class QgsLayerTreeEmbeddedWidgetRegistry
+ * Registry of widgets that may be embedded into layer tree view.
+ * Embedded widgets are assigned per individual map layers and they are shown before any legend entries.
+ * Layer tree must have UseEmbeddedWidgets flag enabled in order to show assigned widgets.
+ *
+ * @see QgsLayerTreeEmbeddedWidgetRegistry
+ * @note introduced in QGIS 2.16
+ */
 class GUI_EXPORT QgsLayerTreeEmbeddedWidgetRegistry
 {
   public:
@@ -52,6 +66,7 @@ class GUI_EXPORT QgsLayerTreeEmbeddedWidgetRegistry
 
     ~QgsLayerTreeEmbeddedWidgetRegistry();
 
+    /** Return list of all registered providers */
     QStringList providers() const;
 
     /** Get provider object from the provider's ID */
@@ -66,9 +81,9 @@ class GUI_EXPORT QgsLayerTreeEmbeddedWidgetRegistry
     bool removeProvider( const QString& providerId );
 
   protected:
+    //! Protected constructor - use instance() to access the registry.
     QgsLayerTreeEmbeddedWidgetRegistry();
 
-
     //! storage of all the providers
     QMap<QString, QgsLayerTreeEmbeddedWidgetProvider*> mProviders;
 };

src/gui/layertree/qgslayertreeview.cpp

@@ -131,7 +131,7 @@ void QgsLayerTreeView::modelRowsInserted( const QModelIndex& index, int start, i
   if ( !parentNode )
     return;
 
-  // EMBEDDED WIDGETS
+  // Embedded widgets - replace placeholders in the model by actual widgets
   if ( layerTreeModel()->testFlag( QgsLayerTreeModel::UseEmbeddedWidgets ) && QgsLayerTree::isLayer( parentNode ) )
   {
     QgsLayerTreeLayer* nodeLayer = QgsLayerTree::toLayer( parentNode );
@@ -141,7 +141,6 @@ void QgsLayerTreeView::modelRowsInserted( const QModelIndex& index, int start, i
       QList<QgsLayerTreeModelLegendNode*> legendNodes = layerTreeModel()->layerLegendNodes( nodeLayer );
       for ( int i = 0; i < widgetsCount; ++i )
       {
-        // TODO: check that the legend nodes are actually the placeholders for embedded widgets
         QString providerId = layer->customProperty( QString( "embeddedWidgets/%1/id" ).arg( i ) ).toString();
         if ( QgsLayerTreeEmbeddedWidgetProvider* provider = QgsLayerTreeEmbeddedWidgetRegistry::instance()->provider( providerId ) )
         {