SIP, indentation and documentation updates

qgis · Sep 4, 2017 · a77950c · a77950c
1 parent 44a8a51
commit a77950c
Show file tree

Hide file tree

Showing 9 changed files with 100 additions and 86 deletions.
diff --git a/python/console/console_settings.py b/python/console/console_settings.py
@@ -30,6 +30,7 @@
 
 
 class optionsDialog(QDialog, Ui_SettingsDialogPythonConsole):
+
     def __init__(self, parent):
         QDialog.__init__(self, parent)
         self.setWindowTitle(QCoreApplication.translate(

diff --git a/python/core/core_auto.sip b/python/core/core_auto.sip
@@ -156,7 +156,6 @@
 %Include composer/qgspaperitem.sip
 %Include layout/qgslayoutcontext.sip
 %Include layout/qgslayoutgridsettings.sip
-%Include layout/qgslayoutitemundocommand.sip
 %Include layout/qgslayoutmeasurement.sip
 %Include layout/qgslayoutmeasurementconverter.sip
 %Include layout/qgspagesizeregistry.sip

diff --git a/python/core/layout/qgslayout.sip b/python/core/layout/qgslayout.sip
@@ -39,8 +39,6 @@ class QgsLayout : QGraphicsScene, QgsExpressionContextGenerator, QgsLayoutUndoOb
  called on the new layout.
 %End
 
-    ~QgsLayout();
-
     void initializeDefaults();
 %Docstring
  Initializes an empty layout, e.g. by adding a default page to the layout. This should be called after creating

diff --git a/python/core/layout/qgslayoutitemundocommand.sip b/python/core/layout/qgslayoutitemundocommand.sip
diff --git a/python/core/layout/qgslayoutpagecollection.sip b/python/core/layout/qgslayoutpagecollection.sip
@@ -231,6 +231,13 @@ class QgsLayoutPageCollection : QObject, QgsLayoutSerializableObject
  :rtype: bool
 %End
 
+    QgsLayoutGuideCollection &guides();
+%Docstring
+ Returns a reference to the collection's guide collection, which manages page snap guides.
+ :rtype: QgsLayoutGuideCollection
+%End
+
+
   public slots:
 
     void redraw();

diff --git a/python/core/layout/qgslayoutundostack.sip b/python/core/layout/qgslayoutundostack.sip
@@ -28,8 +28,29 @@ class QgsLayoutUndoStack
 %End
 
     void beginMacro( const QString &commandText );
+%Docstring
+ Starts a macro command, with the given descriptive ``commandText``.
+
+ Any commands added to the stack (either via direct manipulation of
+ stack() or via beginCommand()/endCommand() calls) between a
+ beginMacro() and endMacro() block are collapsed into a single
+ undo command, which will be applied or rolled back in a single step.
+
+.. seealso:: endMacro()
+%End
 
     void endMacro();
+%Docstring
+ Ends a macro command. This must be called after beginMacro(), when
+ all child undo commands which form part of the macro have been completed.
+
+ Any commands added to the stack (either via direct manipulation of
+ stack() or via beginCommand()/endCommand() calls) between a
+ beginMacro() and endMacro() block are collapsed into a single
+ undo command, which will be applied or rolled back in a single step.
+
+.. seealso:: beginMacro()
+%End
 
     void beginCommand( QgsLayoutUndoObjectInterface *object, const QString &commandText, int id = 0 );
 %Docstring

diff --git a/src/core/layout/qgslayoutitemundocommand.cpp b/src/core/layout/qgslayoutitemundocommand.cpp
@@ -21,6 +21,7 @@
 #include "qgslayout.h"
 #include "qgsproject.h"
 
+///@cond PRIVATE
 QgsLayoutItemUndoCommand::QgsLayoutItemUndoCommand( QgsLayoutItem *item, const QString &text, int id, QUndoCommand *parent )
   : QgsAbstractLayoutUndoCommand( text, id, parent )
   , mItemUuid( item->uuid() )
@@ -118,3 +119,5 @@ void QgsLayoutItemDeleteUndoCommand::redo()
   layout()->removeItem( item );
   item->deleteLater();
 }
+
+///@endcond
diff --git a/src/core/layout/qgslayoutitemundocommand.h b/src/core/layout/qgslayoutitemundocommand.h
@@ -24,16 +24,45 @@
 class QgsLayout;
 class QgsLayoutItem;
 
+SIP_NO_FILE
+
+///@cond PRIVATE
+
+/**
+ * \ingroup core
+ * An undo command subclass for layout item undo commands.
+ *
+ * QgsLayoutItemUndoCommand is a specific layout undo command which is
+ * designed for use with QgsLayoutItems. It automatically handles
+ * recreating a deleted item when the undo stack rolls back past
+ * the item deletion command.
+ *
+ * \since QGIS 3.0
+*/
 class CORE_EXPORT QgsLayoutItemUndoCommand: public QgsAbstractLayoutUndoCommand
 {
   public:
 
+    /**
+     * Constructor for QgsLayoutItemUndoCommand.
+     * \param item associated layout item
+     * \param text undo command descriptive text
+     * \param id optional undo command id, used for automatic command merging
+     * \param parent command
+     */
     QgsLayoutItemUndoCommand( QgsLayoutItem *item, const QString &text, int id = 0, QUndoCommand *parent SIP_TRANSFERTHIS = nullptr );
 
     bool mergeWith( const QUndoCommand *command ) override;
 
+    /**
+     * Returns the layout associated with this command.
+     */
     QgsLayout *layout() const;
 
+    /**
+     * Returns the associated item's UUID, which uniquely identifies the item
+     * within the layout.
+     */
     QString itemUuid() const;
 
   protected:
@@ -51,15 +80,33 @@ class CORE_EXPORT QgsLayoutItemUndoCommand: public QgsAbstractLayoutUndoCommand
 
 };
 
+/**
+ * \ingroup core
+ * An undo command subclass for layout item deletion undo commands.
+ *
+ * QgsLayoutItemDeleteUndoCommand is a specific layout undo command which handles
+ * layout item deletion. When applied (e.g. as a result of a 'redo' action),
+ * the associated layout item is deleted and removed from the layout.
+ *
+ * \since QGIS 3.0
+*/
 class CORE_EXPORT QgsLayoutItemDeleteUndoCommand: public QgsLayoutItemUndoCommand
 {
   public:
 
+    /**
+     * Constructor for QgsLayoutItemDeleteUndoCommand.
+     * \param item associated layout item
+     * \param text undo command descriptive text
+     * \param id optional undo command id, used for automatic command merging
+     * \param parent command
+     */
     QgsLayoutItemDeleteUndoCommand( QgsLayoutItem *item, const QString &text, int id = 0, QUndoCommand *parent SIP_TRANSFERTHIS = nullptr );
     bool mergeWith( const QUndoCommand *command ) override;
     void redo() override;
 
 };
 
+///@endcond
 
 #endif
diff --git a/src/core/layout/qgslayoutundostack.h b/src/core/layout/qgslayoutundostack.h
@@ -40,8 +40,29 @@ class CORE_EXPORT QgsLayoutUndoStack
      */
     QgsLayoutUndoStack( QgsLayout *layout );
 
+    /**
+     * Starts a macro command, with the given descriptive \a commandText.
+     *
+     * Any commands added to the stack (either via direct manipulation of
+     * stack() or via beginCommand()/endCommand() calls) between a
+     * beginMacro() and endMacro() block are collapsed into a single
+     * undo command, which will be applied or rolled back in a single step.
+     *
+     * \see endMacro()
+     */
     void beginMacro( const QString &commandText );
 
+    /**
+     * Ends a macro command. This must be called after beginMacro(), when
+     * all child undo commands which form part of the macro have been completed.
+     *
+     * Any commands added to the stack (either via direct manipulation of
+     * stack() or via beginCommand()/endCommand() calls) between a
+     * beginMacro() and endMacro() block are collapsed into a single
+     * undo command, which will be applied or rolled back in a single step.
+     *
+     * \see beginMacro()
+     */
     void endMacro();
 
     /**