Add some documentation to vector layer properties related classes mov…

…ed to GUI
qgis · Mar 9, 2020 · e45bea5 · e45bea5
1 parent 7c79610
commit e45bea5
Show file tree

Hide file tree

Showing 10 changed files with 129 additions and 25 deletions.
diff --git a/src/gui/labeling/qgslabelengineconfigdialog.h b/src/gui/labeling/qgslabelengineconfigdialog.h
@@ -27,18 +27,29 @@
 class QgsMapCanvas;
 class QgsMessageBar;
 
+/**
+ * \ingroup gui
+ * Widget for configuring the labeling engine
+ *
+ * \note This class is not a part of public API
+ * \since QGIS 3.14
+ */
 class GUI_EXPORT QgsLabelEngineConfigWidget : public QgsPanelWidget, private Ui::QgsLabelEngineConfigWidgetBase
 {
     Q_OBJECT
   public:
+    //! constructor
     QgsLabelEngineConfigWidget( QgsMapCanvas *canvas, QWidget *parent = nullptr );
 
     QMenu *menuButtonMenu() override;
     QString menuButtonTooltip() const override;
 
   public slots:
+    //! Applies the changes
     void apply();
+    //! Resets the settings to the defaults
     void setDefaults();
+    //! Shows the help
     void showHelp();
 
   private:
@@ -49,12 +60,19 @@ class GUI_EXPORT QgsLabelEngineConfigWidget : public QgsPanelWidget, private Ui:
     QgsLabelingEngineSettings::PlacementEngineVersion mPreviousEngineVersion = QgsLabelingEngineSettings::PlacementEngineVersion2;
 };
 
+/**
+ * \ingroup gui
+ * Dialog for configuring the labeling engine
+ *
+ * \note This class is not a part of public API
+ * \since QGIS 3.14
+ */
 class GUI_EXPORT QgsLabelEngineConfigDialog : public QDialog
 {
     Q_OBJECT
 
   public:
-
+    //! constructor
     QgsLabelEngineConfigDialog( QgsMapCanvas *canvas, QWidget *parent = nullptr );
 
     void accept() override;

diff --git a/src/gui/labeling/qgslabelingwidget.h b/src/gui/labeling/qgslabelingwidget.h
@@ -35,12 +35,17 @@ class QgsMapLayer;
 class QgsMessageBar;
 
 /**
+ * \ingroup gui
  * Master widget for configuration of labeling of a vector layer
+ *
+ * \note This class is not a part of public API
+ * \since QGIS 3.14
  */
 class GUI_EXPORT QgsLabelingWidget : public QgsMapLayerConfigWidget, private Ui::QgsLabelingWidget
 {
     Q_OBJECT
   public:
+    //! constructor
     QgsLabelingWidget( QgsVectorLayer *layer, QgsMapCanvas *canvas, QWidget *parent = nullptr, QgsMessageBar *messageBar = nullptr );
 
     /**
@@ -51,6 +56,7 @@ class GUI_EXPORT QgsLabelingWidget : public QgsMapLayerConfigWidget, private Ui:
     QgsLabelingGui *labelingGui();
 
   public slots:
+    //! Sets the layer to configure
     void setLayer( QgsMapLayer *layer );
     //! save config to layer
     void writeSettingsToLayer();
@@ -61,13 +67,14 @@ class GUI_EXPORT QgsLabelingWidget : public QgsMapLayerConfigWidget, private Ui:
     //! reload the settings shown in the dialog from the current layer
     void adaptToLayer();
 
+    //! Reset the settings
     void resetSettings();
 
   signals:
-
+    //! Emitted when an auxiliary field is created
     void auxiliaryFieldCreated();
 
-  protected slots:
+  private slots:
     void labelModeChanged( int index );
     void showEngineConfigDialog();
 

diff --git a/src/gui/labeling/qgsrulebasedlabelingwidget.h b/src/gui/labeling/qgsrulebasedlabelingwidget.h
@@ -31,11 +31,19 @@ class QgsMapCanvas;
 class QgsVectorLayer;
 
 
+/**
+ * \ingroup gui
+ * Model for rule based rendering rules view.
+ *
+ * \note This class is not a part of public API
+ * \since QGIS 3.14
+ */
 class GUI_EXPORT QgsRuleBasedLabelingModel : public QAbstractItemModel
 {
     Q_OBJECT
 
   public:
+    //! constructor
     QgsRuleBasedLabelingModel( QgsRuleBasedLabeling::Rule *rootRule, QObject *parent = nullptr );
 
     Qt::ItemFlags flags( const QModelIndex &index ) const override;
@@ -62,15 +70,25 @@ class GUI_EXPORT QgsRuleBasedLabelingModel : public QAbstractItemModel
 
     // new methods
 
+    //! Returns the rule at the specified index
     QgsRuleBasedLabeling::Rule *ruleForIndex( const QModelIndex &index ) const;
 
+    //! Inserts a new rule at the specified position
     void insertRule( const QModelIndex &parent, int before, QgsRuleBasedLabeling::Rule *newrule );
+    //! Updates the rule at the specified position
     void updateRule( const QModelIndex &parent, int row );
-    // update rule and all its descendants
+    //! Update rule and all its descendants
     void updateRule( const QModelIndex &index );
+    //! Removes the rule at the specified position
     void removeRule( const QModelIndex &index );
 
+    //! Notify the model that new rules will be added
     void willAddRules( const QModelIndex &parent, int count ); // call beginInsertRows
+
+    /**
+     * Notify the model that one is done inserting new rules
+     * \see willAddRules()
+     */
     void finishedAddingRules(); // call endInsertRows
 
   protected:
@@ -81,10 +99,18 @@ class GUI_EXPORT QgsRuleBasedLabelingModel : public QAbstractItemModel
 class QgsLabelingRulePropsWidget;
 
 
+/**
+ * \ingroup gui
+ * Widget for configuring rule based labeling
+ *
+ * \note This class is not a part of public API
+ * \since QGIS 3.14
+ */
 class GUI_EXPORT QgsRuleBasedLabelingWidget : public QgsPanelWidget, private Ui::QgsRuleBasedLabelingWidget
 {
     Q_OBJECT
   public:
+    //! constructor
     QgsRuleBasedLabelingWidget( QgsVectorLayer *layer, QgsMapCanvas *canvas, QWidget *parent = nullptr );
     ~QgsRuleBasedLabelingWidget() override;
 
@@ -93,22 +119,19 @@ class GUI_EXPORT QgsRuleBasedLabelingWidget : public QgsPanelWidget, private Ui:
 
     void setDockMode( bool dockMode ) override;
 
-  protected slots:
+  private slots:
     void addRule();
     void editRule();
     void editRule( const QModelIndex &index );
     void removeRule();
     void copy();
     void paste();
-
-  private slots:
     void ruleWidgetPanelAccepted( QgsPanelWidget *panel );
     void liveUpdateRuleFromPanel();
 
-  protected:
+  private:
     QgsRuleBasedLabeling::Rule *currentRule();
 
-  protected:
     QgsVectorLayer *mLayer = nullptr;
     QgsMapCanvas *mCanvas = nullptr;
 
@@ -127,35 +150,37 @@ class QgsLabelingGui;
 
 #include "ui_qgslabelingrulepropswidget.h"
 
+/**
+ * \ingroup gui
+ * Widget for editing a labeling rule
+ *
+ * \note This class is not a part of public API
+ * \since QGIS 3.14
+ */
 class GUI_EXPORT QgsLabelingRulePropsWidget : public QgsPanelWidget, private Ui::QgsLabelingRulePropsWidget
 {
     Q_OBJECT
 
   public:
-    enum Mode
-    {
-      Adding,
-      Editing
-    };
-
+    //! constructor
     QgsLabelingRulePropsWidget( QgsRuleBasedLabeling::Rule *rule, QgsVectorLayer *layer,
                                 QWidget *parent = nullptr, QgsMapCanvas *mapCanvas = nullptr );
     ~QgsLabelingRulePropsWidget() override;
 
+    //! Returns the rule being edited
     QgsRuleBasedLabeling::Rule *rule() { return mRule; }
 
     void setDockMode( bool dockMode ) override;
 
   public slots:
+    //! Apply any changes from the widget to the set rule.
+    void apply();
+
+  private slots:
     void testFilter();
     void buildExpression();
 
-    /**
-     * Apply any changes from the widget to the set rule.
-     */
-    void apply();
-
-  protected:
+  private:
     QgsRuleBasedLabeling::Rule *mRule; // borrowed
     QgsVectorLayer *mLayer = nullptr;
 

diff --git a/src/gui/qgsaddattrdialog.h b/src/gui/qgsaddattrdialog.h
@@ -28,18 +28,28 @@
 
 class QgsVectorLayer;
 
+/**
+ * \ingroup gui
+ * Dialog to add a source field attribute
+ *
+ * \note This class is not a part of public API
+ * \since QGIS 3.14
+ */
 class GUI_EXPORT QgsAddAttrDialog: public QDialog, private Ui::QgsAddAttrDialogBase
 {
     Q_OBJECT
   public:
+    //! constructor
     QgsAddAttrDialog( QgsVectorLayer *vlayer,
                       QWidget *parent = nullptr, Qt::WindowFlags fl = QgsGuiUtils::ModalDialogFlags );
+    //! constructor
     QgsAddAttrDialog( const std::list<QString> &typelist,
                       QWidget *parent = nullptr, Qt::WindowFlags fl = QgsGuiUtils::ModalDialogFlags );
 
+    //! Returns a field for the configured attribute
     QgsField field() const;
 
-  public slots:
+  private slots:
     void mTypeBox_currentIndexChanged( int idx );
     void mLength_editingFinished();
     void accept() override;

diff --git a/src/gui/qgsaddtaborgroup.h b/src/gui/qgsaddtaborgroup.h
@@ -30,6 +30,13 @@
 class QTreeWidgetItem;
 class QgsVectorLayer;
 
+/**
+ * \ingroup gui
+ * Dialog to add a tab or group of attributes
+ *
+ * \note This class is not a part of public API
+ * \since QGIS 3.14
+ */
 class GUI_EXPORT QgsAddTabOrGroup : public QDialog, private Ui::QgsAddTabOrGroupBase
 {
     Q_OBJECT
@@ -38,16 +45,22 @@ class GUI_EXPORT QgsAddTabOrGroup : public QDialog, private Ui::QgsAddTabOrGroup
     typedef QPair<QString, QTreeWidgetItem *> TabPair;
 
   public:
+    //! constructor
     QgsAddTabOrGroup( QgsVectorLayer *lyr, const QList<TabPair> &tabList, QWidget *parent = nullptr );
 
+    //! Returns the name of the tab or group
     QString name();
 
+    //! Returns tree item corresponding to the added tab
     QTreeWidgetItem *tab();
 
+    //! Returns the column count
     int columnCount() const;
 
+    //! Returns whether the tab button is checked
     bool tabButtonIsChecked();
 
+    //! Accepts the dialog
     void accept() override;
 
   private slots:

diff --git a/src/gui/qgsmaplayerstylecategoriesmodel.h b/src/gui/qgsmaplayerstylecategoriesmodel.h
@@ -24,20 +24,28 @@
 #include "qgsmaplayer.h"
 #include "qgis_gui.h"
 
+/**
+ * \ingroup gui
+ * Model for layer style categories
+ *
+ * \note This class is not a part of public API
+ * \since QGIS 3.14
+ */
 class GUI_EXPORT QgsMapLayerStyleCategoriesModel : public QAbstractListModel
 {
     Q_OBJECT
 
   public:
+    //! constructor
     explicit QgsMapLayerStyleCategoriesModel( QObject *parent = nullptr );
 
-    //! reset the model data
+    //! Reset the model data
     void setCategories( QgsMapLayer::StyleCategories categories );
 
-    //! return the categories as defined in the model
+    //! Returns the categories as defined in the model
     QgsMapLayer::StyleCategories categories() const;
 
-    //! defines if the model should list the AllStyleCategories entry
+    //! Defines if the model should list the AllStyleCategories entry
     void setShowAllCategories( bool showAll );
 
     int rowCount( const QModelIndex & = QModelIndex() ) const override;

diff --git a/src/gui/qgsmaskingwidget.cpp b/src/gui/qgsmaskingwidget.cpp
@@ -45,14 +45,19 @@ QgsMaskingWidget::QgsMaskingWidget( QWidget *parent ) :
 }
 
 /**
+ * \ingroup gui
  * Generic visitor that collects symbol layers of a vector layer's renderer
  * and call a callback function on them with their corresponding QgsSymbolLayerId
+ *
+ * \note This class is not a part of public API
+ * \since QGIS 3.14
  */
 class SymbolLayerVisitor : public QgsStyleEntityVisitorInterface
 {
   public:
     typedef std::function<void( const QgsSymbolLayer *, const QgsSymbolLayerId & )> SymbolLayerCallback;
 
+    //! constructor
     SymbolLayerVisitor( SymbolLayerCallback callback ) :
       mCallback( callback )
     {}
@@ -66,6 +71,7 @@ class SymbolLayerVisitor : public QgsStyleEntityVisitorInterface
       return true;
     }
 
+    //! Process a symbol
     void visitSymbol( const QgsSymbol *symbol, const QString &leafIdentifier, QVector<int> rootPath )
     {
       for ( int idx = 0; idx < symbol->symbolLayerCount(); idx++ )

diff --git a/src/gui/qgsmaskingwidget.h b/src/gui/qgsmaskingwidget.h
@@ -24,19 +24,29 @@
 #include "qgis_gui.h"
 
 /**
+ * \ingroup gui
  * Main widget for the configuration of mask sources and targets.
+ *
+ * \note This class is not a part of public API
+ * \since QGIS 3.14
  */
 class GUI_EXPORT QgsMaskingWidget: public QgsPanelWidget, private Ui::QgsMaskingWidgetBase
 {
     Q_OBJECT
   public:
+    //! constructor
     QgsMaskingWidget( QWidget *parent = nullptr );
 
+    //! Sets the layer to configure
     void setLayer( QgsVectorLayer *layer );
 
+    //! Applies the changes
     void apply();
+
   signals:
+    //! Emitted when a change is performed
     void widgetChanged();
+
   private:
     QgsVectorLayer *mLayer;
 };