Cleanup some CPT city docs

python/PyQt6/core/auto_additions/qgscptcityarchive.py

@@ -7,6 +7,10 @@ QgsCptCityDataItem.AllRamps = QgsCptCityDataItem.Type.AllRamps
 QgsCptCityBrowserModel.Authors = QgsCptCityBrowserModel.ViewType.Authors
 QgsCptCityBrowserModel.Selections = QgsCptCityBrowserModel.ViewType.Selections
 QgsCptCityBrowserModel.List = QgsCptCityBrowserModel.ViewType.List
+try:
+    QgsCptCityDataItem.__attribute_docs__ = {'beginInsertItems': 'Emitted before child items are added to this item.\n\nThis signal *must* be followed by :py:func:`~QgsCptCityDataItem.endInsertItems`.\n\n:param parent: the parent item having children added\n:param first: index of first child item to be added\n:param last: index last child item, after the addition has occurred\n\n.. seealso:: :py:func:`endInsertItems`\n', 'endInsertItems': 'Emitted after child items have been added to this data item.\n\nThis signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginInsertItems`.\n\n.. seealso:: :py:func:`beginInsertItems`\n', 'beginRemoveItems': 'Emitted before child items are removed from this data item.\n\nThis signal *must* be followed by :py:func:`~QgsCptCityDataItem.endRemoveItems`.\n\n:param parent: the parent item having children removed\n:param first: index of first child item to be removed\n:param last: index of the last child item to be removed\n\n.. seealso:: :py:func:`endRemoveItems`\n', 'endRemoveItems': 'Emitted after child items have been removed from this data item.\n\nThis signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginRemoveItems`.\n\n.. seealso:: :py:func:`beginRemoveItems`\n'}
+except NameError:
+    pass
 QgsCptCityArchive.defaultBaseDir = staticmethod(QgsCptCityArchive.defaultBaseDir)
 QgsCptCityArchive.findFileName = staticmethod(QgsCptCityArchive.findFileName)
 QgsCptCityArchive.copyingInfo = staticmethod(QgsCptCityArchive.copyingInfo)

python/PyQt6/core/auto_generated/symbology/qgscptcityarchive.sip.in

@@ -78,32 +78,85 @@ Base class for all items in the model
     bool hasChildren();
 
     int rowCount();
+
     virtual int leafCount() const;
+%Docstring
+Returns the total count of "leaf" items (all children which are end nodes).
+%End
 
 
     virtual void refresh();
 
     virtual QVector<QgsCptCityDataItem *> createChildren();
+%Docstring
+Returns a vector of children items.
+%End
 
     virtual void populate();
+%Docstring
+Populates children using children vector created by :py:func:`~QgsCptCityDataItem.createChildren`.
+%End
+
     bool isPopulated();
+%Docstring
+Returns ``True`` if the item is already populated.
+%End
 
     virtual void addChildItem( QgsCptCityDataItem *child /Transfer/, bool refresh = false );
+%Docstring
+Inserts a new ``child`` using alphabetical order based on mName, emits necessary signal to model before and after, sets parent and connects signals.
+
+The ``refresh`` argument will refresh the populated item by emitting signals to the model.
+%End
 
     virtual void deleteChildItem( QgsCptCityDataItem *child );
+%Docstring
+Removes and deletes a child ``item``, signals to browser are emitted.
+%End
 
     virtual QgsCptCityDataItem *removeChildItem( QgsCptCityDataItem *child ) /TransferBack/;
+%Docstring
+Removes a ``child`` item but doesn't delete it, signals to browser are emitted.
+
+:return: pointer to the removed item or ``None`` if no such item was found
+%End
 
     virtual bool equal( const QgsCptCityDataItem *other );
+%Docstring
+Returns ``True`` if this item is equal to an ``other`` item.
+%End
 
-    virtual QWidget *paramWidget() /Factory/;
+ virtual QWidget *paramWidget() /Deprecated/;
+%Docstring
 
-    virtual bool acceptDrop();
+.. deprecated:: 3.40
 
-    virtual bool handleDrop( const QMimeData * /*data*/, Qt::DropAction /*action*/ );
+   Is unused and will be removed in QGIS 4.0.
+%End
+
+ virtual bool acceptDrop() /Deprecated/;
+%Docstring
+Returns ``True`` if the item accepts drag & dropped layers - e.g. for import.
+
+.. deprecated:: 3.40
+
+   Is unused and will be removed in QGIS 4.0.
+%End
+
+ virtual bool handleDrop( const QMimeData *data, Qt::DropAction action ) /Deprecated/;
+%Docstring
+Tries to process the ``data`` dropped on this item.
+
+.. deprecated:: 3.40
+
+   Is unused and will be removed in QGIS 4.0.
+%End
 
 
     static int findItem( QVector<QgsCptCityDataItem *> items, QgsCptCityDataItem *item );
+%Docstring
+Finds a child index in vector of items using '==' operator.
+%End
 
 
     Type type() const;
@@ -128,10 +181,50 @@ Base class for all items in the model
 
 
   signals:
+
     void beginInsertItems( QgsCptCityDataItem *parent, int first, int last );
+%Docstring
+Emitted before child items are added to this item.
+
+This signal *must* be followed by :py:func:`~QgsCptCityDataItem.endInsertItems`.
+
+:param parent: the parent item having children added
+:param first: index of first child item to be added
+:param last: index last child item, after the addition has occurred
+
+.. seealso:: :py:func:`endInsertItems`
+%End
+
     void endInsertItems();
+%Docstring
+Emitted after child items have been added to this data item.
+
+This signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginInsertItems`.
+
+.. seealso:: :py:func:`beginInsertItems`
+%End
+
     void beginRemoveItems( QgsCptCityDataItem *parent, int first, int last );
+%Docstring
+Emitted before child items are removed from this data item.
+
+This signal *must* be followed by :py:func:`~QgsCptCityDataItem.endRemoveItems`.
+
+:param parent: the parent item having children removed
+:param first: index of first child item to be removed
+:param last: index of the last child item to be removed
+
+.. seealso:: :py:func:`endRemoveItems`
+%End
+
     void endRemoveItems();
+%Docstring
+Emitted after child items have been removed from this data item.
+
+This signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginRemoveItems`.
+
+.. seealso:: :py:func:`beginRemoveItems`
+%End
 };
 
 class QgsCptCityColorRampItem : QgsCptCityDataItem
@@ -331,8 +424,6 @@ Returns index of a path
     virtual void fetchMore( const QModelIndex &parent );
 
 
-  signals:
-
   public slots:
 
     void beginInsertItems( QgsCptCityDataItem *parent, int first, int last );

python/core/auto_additions/qgscptcityarchive.py

@@ -1,4 +1,8 @@
 # The following has been generated automatically from src/core/symbology/qgscptcityarchive.h
+try:
+    QgsCptCityDataItem.__attribute_docs__ = {'beginInsertItems': 'Emitted before child items are added to this item.\n\nThis signal *must* be followed by :py:func:`~QgsCptCityDataItem.endInsertItems`.\n\n:param parent: the parent item having children added\n:param first: index of first child item to be added\n:param last: index last child item, after the addition has occurred\n\n.. seealso:: :py:func:`endInsertItems`\n', 'endInsertItems': 'Emitted after child items have been added to this data item.\n\nThis signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginInsertItems`.\n\n.. seealso:: :py:func:`beginInsertItems`\n', 'beginRemoveItems': 'Emitted before child items are removed from this data item.\n\nThis signal *must* be followed by :py:func:`~QgsCptCityDataItem.endRemoveItems`.\n\n:param parent: the parent item having children removed\n:param first: index of first child item to be removed\n:param last: index of the last child item to be removed\n\n.. seealso:: :py:func:`endRemoveItems`\n', 'endRemoveItems': 'Emitted after child items have been removed from this data item.\n\nThis signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginRemoveItems`.\n\n.. seealso:: :py:func:`beginRemoveItems`\n'}
+except NameError:
+    pass
 QgsCptCityArchive.defaultBaseDir = staticmethod(QgsCptCityArchive.defaultBaseDir)
 QgsCptCityArchive.findFileName = staticmethod(QgsCptCityArchive.findFileName)
 QgsCptCityArchive.copyingInfo = staticmethod(QgsCptCityArchive.copyingInfo)

python/core/auto_generated/symbology/qgscptcityarchive.sip.in

@@ -78,32 +78,85 @@ Base class for all items in the model
     bool hasChildren();
 
     int rowCount();
+
     virtual int leafCount() const;
+%Docstring
+Returns the total count of "leaf" items (all children which are end nodes).
+%End
 
 
     virtual void refresh();
 
     virtual QVector<QgsCptCityDataItem *> createChildren();
+%Docstring
+Returns a vector of children items.
+%End
 
     virtual void populate();
+%Docstring
+Populates children using children vector created by :py:func:`~QgsCptCityDataItem.createChildren`.
+%End
+
     bool isPopulated();
+%Docstring
+Returns ``True`` if the item is already populated.
+%End
 
     virtual void addChildItem( QgsCptCityDataItem *child /Transfer/, bool refresh = false );
+%Docstring
+Inserts a new ``child`` using alphabetical order based on mName, emits necessary signal to model before and after, sets parent and connects signals.
+
+The ``refresh`` argument will refresh the populated item by emitting signals to the model.
+%End
 
     virtual void deleteChildItem( QgsCptCityDataItem *child );
+%Docstring
+Removes and deletes a child ``item``, signals to browser are emitted.
+%End
 
     virtual QgsCptCityDataItem *removeChildItem( QgsCptCityDataItem *child ) /TransferBack/;
+%Docstring
+Removes a ``child`` item but doesn't delete it, signals to browser are emitted.
+
+:return: pointer to the removed item or ``None`` if no such item was found
+%End
 
     virtual bool equal( const QgsCptCityDataItem *other );
+%Docstring
+Returns ``True`` if this item is equal to an ``other`` item.
+%End
 
-    virtual QWidget *paramWidget() /Factory/;
+ virtual QWidget *paramWidget() /Deprecated/;
+%Docstring
 
-    virtual bool acceptDrop();
+.. deprecated:: 3.40
 
-    virtual bool handleDrop( const QMimeData * /*data*/, Qt::DropAction /*action*/ );
+   Is unused and will be removed in QGIS 4.0.
+%End
+
+ virtual bool acceptDrop() /Deprecated/;
+%Docstring
+Returns ``True`` if the item accepts drag & dropped layers - e.g. for import.
+
+.. deprecated:: 3.40
+
+   Is unused and will be removed in QGIS 4.0.
+%End
+
+ virtual bool handleDrop( const QMimeData *data, Qt::DropAction action ) /Deprecated/;
+%Docstring
+Tries to process the ``data`` dropped on this item.
+
+.. deprecated:: 3.40
+
+   Is unused and will be removed in QGIS 4.0.
+%End
 
 
     static int findItem( QVector<QgsCptCityDataItem *> items, QgsCptCityDataItem *item );
+%Docstring
+Finds a child index in vector of items using '==' operator.
+%End
 
 
     Type type() const;
@@ -128,10 +181,50 @@ Base class for all items in the model
 
 
   signals:
+
     void beginInsertItems( QgsCptCityDataItem *parent, int first, int last );
+%Docstring
+Emitted before child items are added to this item.
+
+This signal *must* be followed by :py:func:`~QgsCptCityDataItem.endInsertItems`.
+
+:param parent: the parent item having children added
+:param first: index of first child item to be added
+:param last: index last child item, after the addition has occurred
+
+.. seealso:: :py:func:`endInsertItems`
+%End
+
     void endInsertItems();
+%Docstring
+Emitted after child items have been added to this data item.
+
+This signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginInsertItems`.
+
+.. seealso:: :py:func:`beginInsertItems`
+%End
+
     void beginRemoveItems( QgsCptCityDataItem *parent, int first, int last );
+%Docstring
+Emitted before child items are removed from this data item.
+
+This signal *must* be followed by :py:func:`~QgsCptCityDataItem.endRemoveItems`.
+
+:param parent: the parent item having children removed
+:param first: index of first child item to be removed
+:param last: index of the last child item to be removed
+
+.. seealso:: :py:func:`endRemoveItems`
+%End
+
     void endRemoveItems();
+%Docstring
+Emitted after child items have been removed from this data item.
+
+This signal will always be preceded by :py:func:`~QgsCptCityDataItem.beginRemoveItems`.
+
+.. seealso:: :py:func:`beginRemoveItems`
+%End
 };
 
 class QgsCptCityColorRampItem : QgsCptCityDataItem
@@ -331,8 +424,6 @@ Returns index of a path
     virtual void fetchMore( const QModelIndex &parent );
 
 
-  signals:
-
   public slots:
 
     void beginInsertItems( QgsCptCityDataItem *parent, int first, int last );

src/core/symbology/qgscptcityarchive.h

@@ -114,44 +114,79 @@ class CORE_EXPORT QgsCptCityDataItem : public QObject
     bool hasChildren();
 
     int rowCount();
-    // retrieve total count of "leaf" items (all children which are end nodes)
+
+    /**
+     * Returns the total count of "leaf" items (all children which are end nodes).
+     */
     virtual int leafCount() const;
 
     //
 
     virtual void refresh();
 
-    // Create vector of children
+    /**
+     * Returns a vector of children items.
+     */
     virtual QVector<QgsCptCityDataItem *> createChildren();
 
-    // Populate children using children vector created by createChildren()
+    /**
+     * Populates children using children vector created by createChildren().
+     */
     virtual void populate();
+
+    /**
+     * Returns TRUE if the item is already populated.
+     */
     bool isPopulated() { return mPopulated; }
 
-    // Insert new child using alphabetical order based on mName, emits necessary signal to model before and after, sets parent and connects signals
-    // refresh - refresh populated item, emit signals to model
+    /**
+     * Inserts a new \a child using alphabetical order based on mName, emits necessary signal to model before and after, sets parent and connects signals.
+     *
+     * The \a refresh argument will refresh the populated item by emitting signals to the model.
+     */
     virtual void addChildItem( QgsCptCityDataItem *child SIP_TRANSFER, bool refresh = false );
 
-    // remove and delete child item, signals to browser are emitted
+    /**
+     * Removes and deletes a child \a item, signals to browser are emitted.
+     */
     virtual void deleteChildItem( QgsCptCityDataItem *child );
 
-    // remove child item but don't delete it, signals to browser are emitted
-    // returns pointer to the removed item or null if no such item was found
+    /**
+     * Removes a \a child item but doesn't delete it, signals to browser are emitted.
+     *
+     * \returns pointer to the removed item or NULLPTR if no such item was found
+     */
     virtual QgsCptCityDataItem *removeChildItem( QgsCptCityDataItem *child ) SIP_TRANSFERBACK;
 
+    /**
+     * Returns TRUE if this item is equal to an \a other item.
+     */
     virtual bool equal( const QgsCptCityDataItem *other );
 
-    virtual QWidget *paramWidget() SIP_FACTORY { return nullptr; }
+    /**
+     * \deprecated QGIS 3.40. Is unused and will be removed in QGIS 4.0.
+     */
+    Q_DECL_DEPRECATED virtual QWidget *paramWidget() SIP_DEPRECATED { return nullptr; }
 
-    // whether accepts drag&drop'd layers - e.g. for import
-    virtual bool acceptDrop() { return false; }
+    /**
+     * Returns TRUE if the item accepts drag & dropped layers - e.g. for import.
+     *
+     * \deprecated QGIS 3.40. Is unused and will be removed in QGIS 4.0.
+     */
+    Q_DECL_DEPRECATED virtual bool acceptDrop() SIP_DEPRECATED { return false; }
 
-    // try to process the data dropped on this item
-    virtual bool handleDrop( const QMimeData * /*data*/, Qt::DropAction /*action*/ ) { return false; }
+    /**
+     * Tries to process the \a data dropped on this item.
+     *
+     * \deprecated QGIS 3.40. Is unused and will be removed in QGIS 4.0.
+     */
+    Q_DECL_DEPRECATED virtual bool handleDrop( const QMimeData *data, Qt::DropAction action ) SIP_DEPRECATED { Q_UNUSED( data ); Q_UNUSED( action ); return false; }
 
     // static methods
 
-    // Find child index in vector of items using '==' operator
+    /**
+     * Finds a child index in vector of items using '==' operator.
+     */
     static int findItem( QVector<QgsCptCityDataItem *> items, QgsCptCityDataItem *item );
 
     // members
@@ -189,9 +224,49 @@ class CORE_EXPORT QgsCptCityDataItem : public QObject
     bool mValid;
 
   signals:
+
+    /**
+     * Emitted before child items are added to this item.
+     *
+     * This signal *must* be followed by endInsertItems().
+     *
+     * \param parent the parent item having children added
+     * \param first index of first child item to be added
+     * \param last index last child item, after the addition has occurred
+     *
+     * \see endInsertItems()
+     */
     void beginInsertItems( QgsCptCityDataItem *parent, int first, int last );
+
+    /**
+     * Emitted after child items have been added to this data item.
+     *
+     * This signal will always be preceded by beginInsertItems().
+     *
+     * \see beginInsertItems()
+     */
     void endInsertItems();
+
+    /**
+     * Emitted before child items are removed from this data item.
+     *
+     * This signal *must* be followed by endRemoveItems().
+     *
+     * \param parent the parent item having children removed
+     * \param first index of first child item to be removed
+     * \param last index of the last child item to be removed
+     *
+     * \see endRemoveItems()
+     */
     void beginRemoveItems( QgsCptCityDataItem *parent, int first, int last );
+
+    /**
+     * Emitted after child items have been removed from this data item.
+     *
+     * This signal will always be preceded by beginRemoveItems().
+     *
+     * \see beginRemoveItems()
+     */
     void endRemoveItems();
 };
 
@@ -379,8 +454,6 @@ class CORE_EXPORT QgsCptCityBrowserModel : public QAbstractItemModel
     bool canFetchMore( const QModelIndex &parent ) const override;
     void fetchMore( const QModelIndex &parent ) override;
 
-  signals:
-
   public slots:
     //void removeItems( QgsCptCityDataItem * parent, QVector<QgsCptCityDataItem *>items );
     //void addItems( QgsCptCityDataItem * parent, QVector<QgsCptCityDataItem *>items );