Dox++

python/core/auto_generated/qgslegendrenderer.sip.in

@@ -27,46 +27,67 @@ All spacing and sizes are in millimeters.
 #include "qgslegendrenderer.h"
 %End
   public:
+
     QgsLegendRenderer( QgsLayerTreeModel *legendModel, const QgsLegendSettings &settings );
 %Docstring
-Construct legend renderer. The ownership of legend model does not change
+Constructor for QgsLegendRenderer. The ownership of the legend model is not changed,
+and the model must exist for the lifetime of this renderer.
 %End
 
     QSizeF minimumSize();
 %Docstring
-Run the layout algorithm and determine the size required for legend
+Runs the layout algorithm and returns the minimum size required for the legend.
+
+.. seealso:: :py:func:`setLegendSize`
+
+.. seealso:: :py:func:`legendSize`
 %End
 
     void setLegendSize( QSizeF s );
 %Docstring
 Sets the preferred resulting legend size.
+
+If the size is null, the legend will be drawn with the minimum possible size to fit its content.
+
+.. seealso:: :py:func:`legendSize`
+
+.. seealso:: :py:func:`minimumSize`
 %End
 
     QSizeF legendSize() const;
 %Docstring
-Find out preferred legend size set by the client. If null, the legend will be drawn with the minimum size
+Returns the preferred legend size set by the client.
+
+If the returned size is null, the legend will be drawn with the minimum possible size to fit its content.
+
+.. seealso:: :py:func:`minimumSize`
+
+.. seealso:: :py:func:`setLegendSize`
 %End
 
     void drawLegend( QPainter *painter );
 %Docstring
-Draw the legend with given painter. It will occupy the area reported in legendSize().
+Draws the legend with given ``painter``. The legend will occupy the area reported in legendSize().
-Painter should be scaled beforehand so that units correspond to millimeters.
+The ``painter`` should be scaled beforehand so that units correspond to millimeters.
 %End
 
     void drawLegend( QgsRenderContext *rendercontext );
 %Docstring
-Draw the legend using a given :py:class:`QgsRenderContext`. It will occupy the area reported in legendSize().
+Draws the legend using a given :py:class:`QgsRenderContext`. The legend will occupy the area reported in legendSize().
 %End
 
     static void setNodeLegendStyle( QgsLayerTreeNode *node, QgsLegendStyle::Style style );
 %Docstring
-Set the style of a QgsLayerTreeNode,
+Sets the ``style`` of a ``node``.
-This class requires a node and a style to apply to the node
+
+.. seealso:: :py:func:`nodeLegendStyle`
 %End
 
     static QgsLegendStyle::Style nodeLegendStyle( QgsLayerTreeNode *node, QgsLayerTreeModel *model );
 %Docstring
-Returns the style of a given QgsLayerTreeNode in a given :py:class:`QgsLayerTreeModel`
+Returns the style for the given ``node``, within the specified ``model``.
+
+.. seealso:: :py:func:`setNodeLegendStyle`
 %End
 
 };

src/core/qgslegendrenderer.h

@@ -45,37 +45,62 @@ class QgsRenderContext;
 class CORE_EXPORT QgsLegendRenderer
 {
   public:
-    //! Construct legend renderer. The ownership of legend model does not change
+
+    /**
+     * Constructor for QgsLegendRenderer. The ownership of the legend model is not changed,
+     * and the model must exist for the lifetime of this renderer.
+     */
     QgsLegendRenderer( QgsLayerTreeModel *legendModel, const QgsLegendSettings &settings );
 
-    //! Run the layout algorithm and determine the size required for legend
+    /**
+     * Runs the layout algorithm and returns the minimum size required for the legend.
+     * \see setLegendSize()
+     * \see legendSize()
+     */
     QSizeF minimumSize();
 
-    //! Sets the preferred resulting legend size.
+    /**
+     * Sets the preferred resulting legend size.
+     *
+     * If the size is null, the legend will be drawn with the minimum possible size to fit its content.
+     *
+     * \see legendSize()
+     * \see minimumSize()
+     */
     void setLegendSize( QSizeF s ) { mLegendSize = s; }
 
-    //! Find out preferred legend size set by the client. If null, the legend will be drawn with the minimum size
+    /**
+     * Returns the preferred legend size set by the client.
+     *
+     * If the returned size is null, the legend will be drawn with the minimum possible size to fit its content.
+     *
+     * \see minimumSize()
+     * \see setLegendSize()
+     */
     QSizeF legendSize() const { return mLegendSize; }
 
     /**
-     * Draw the legend with given painter. It will occupy the area reported in legendSize().
+     * Draws the legend with given \a painter. The legend will occupy the area reported in legendSize().
-     * Painter should be scaled beforehand so that units correspond to millimeters.
+     * The \a painter should be scaled beforehand so that units correspond to millimeters.
      */
     void drawLegend( QPainter *painter );
 
     /**
-     * Draw the legend using a given QgsRenderContext. It will occupy the area reported in legendSize().
+     * Draws the legend using a given QgsRenderContext. The legend will occupy the area reported in legendSize().
      */
     void drawLegend( QgsRenderContext *rendercontext );
 
     /**
-     * Set the style of a QgsLayerTreeNode,
+     * Sets the \a style of a \a node.
-     * This class requires a node and a style to apply to the node
+     *
+     * \see nodeLegendStyle()
      */
     static void setNodeLegendStyle( QgsLayerTreeNode *node, QgsLegendStyle::Style style );
 
     /**
-     * Returns the style of a given QgsLayerTreeNode in a given QgsLayerTreeModel
+     * Returns the style for the given \a node, within the specified \a model.
+     *
+     * \see setNodeLegendStyle()
      */
     static QgsLegendStyle::Style nodeLegendStyle( QgsLayerTreeNode *node, QgsLayerTreeModel *model );
 
@@ -84,9 +109,11 @@ class CORE_EXPORT QgsLegendRenderer
 #ifndef SIP_RUN
 
     /**
-     * Nucleon is either group title, layer title or layer child item.
+     * A legend Nucleon is either a group title, a layer title or a layer child item.
-     *  E.g. layer title nucleon is just title, it does not
+     *
-     *  include all layer subitems, the same with groups.
+     * E.g. a layer title nucleon is just the layer's title, it does not
+     * include all of that layer's subitems. Similarly, a group's title nucleon is just
+     * the group title, and does not include the actual content of that group.
      */
     class Nucleon
     {
@@ -95,117 +122,165 @@ class CORE_EXPORT QgsLegendRenderer
         Nucleon() = default;
 
         QObject *item = nullptr;
-        // Symbol size size without any space around for symbol item
+
+        //! Symbol size, not including any preset padding space around the symbol
         QSizeF symbolSize;
-        // Label size without any space around for symbol item
+
+        //! Label size, not including any preset padding space around the label
         QSizeF labelSize;
+
+        //! Nucleon size
         QSizeF size;
-        // Offset of symbol label, this offset is the same for all symbol labels
+
-        // of the same layer in the same column
+        /**
+         * Horizontal offset for the symbol label.
+         *
+         * This offset is the same for all symbol labels belonging to the same layer,
+         * within the same legend column.
+         */
         double labelXOffset = 0.0;
     };
 
     /**
-     * Atom is indivisible set (indivisible into more columns). It may consists
+     * An Atom is indivisible set of legend Nucleons (i.e. it is indivisible into more columns).
-     *  of one or more Nucleon, depending on layer splitting mode:
+     *
+     * An Atom may consist of one or more Nucleon(s), depending on the layer splitting mode:
+     *
      *  1) no layer split: [group_title ...] layer_title layer_item [layer_item ...]
      *  2) layer split:    [group_title ...] layer_title layer_item
      *              or:    layer_item
-     *  It means that group titles must not be split from layer title and layer title
+     *
-     *  must not be split from first item, because it would look bad and it would not
+     * This means that group titles must not be split from layer titles and layer titles
-     *  be readable to leave group or layer title at the bottom of column.
+     * must not be split from the first layer item, because this results in a poor layout
+     * and it would not be logical to leave a group or layer title at the bottom of a column,
+     * separated from the actual content of that group or layer.
      */
     class Atom
     {
       public:
-        Atom(): size( QSizeF( 0, 0 ) ) {}
+        Atom();
+
+        //! List of child Nucleons belonging to this Atom.
         QList<Nucleon> nucleons;
-        // Atom size including nucleons interspaces but without any space around atom.
+
-        QSizeF size;
+        //! Atom size, including internal spacing between Nucleons, but excluding any padding space around the Atom itself.
+        QSizeF size = QSizeF( 0, 0 );
+
+        //! Corresponding column index
         int column = 0;
     };
 
     /**
-     * displays the legend and return the size of said legend.
+     * Draws the legend and returns the actual size of the legend.
-     * If the painter is null, only the size will be given,
+     *
-     * since a painter is needed to render the legend.
+     * If \a painter is nullptr, only the size of the legend will be calculated and no
+     * painting will be attempted.
      */
     QSizeF paintAndDetermineSize( QPainter *painter = nullptr );
 
-    //! Create list of atoms according to current layer splitting mode
+    /**
+     * Returns a list of Atoms for the specified \a parentGroup, respecting the current layer's
+     * splitting settings.
+     */
     QList<Atom> createAtomList( QgsLayerTreeGroup *parentGroup, bool splitLayer );
 
-    //! Divide atoms to columns and set columns on atoms
+    /**
+     * Divides a list of Atoms into columns, and sets the column index for each atom in the list.
+     */
     void setColumns( QList<Atom> &atomList );
 
     /**
-     * Draws title in the legend using the title font and the specified alignment
+     * Draws a title in the legend using the title font and the specified alignment settings.
-     * If no painter is specified, function returns the required width/height to draw the title.
+     *
+     * Returns the size required to draw the complete title.
+     *
+     * If \a painter is nullptr, no painting will be attempted, but the required size will still be calculated and returned.
      */
     QSizeF drawTitle( QPainter *painter = nullptr, QPointF point = QPointF(), Qt::AlignmentFlag halignment = Qt::AlignLeft, double legendWidth = 0 );
 
+    /**
+     * Returns the calculated padding space required above the given \a atom.
+     */
     double spaceAboveAtom( const Atom &atom );
 
     /**
-     * Draw atom and return its actual size, the atom is drawn with the space above it
+     * Draws an \a atom and return its actual size.
-     *  so that first atoms in column are all aligned to the same line regardles their
+     *
-     * style top space */
+     * The \a atom is drawn with the space above it, so that the first atoms in column are all
+     * aligned to the same line regardless of their style top spacing.
+    */
     QSizeF drawAtom( const Atom &atom, QPainter *painter = nullptr, QPointF point = QPointF() );
 
     /**
-     * Displays the symbol of a given QgsLayerTreeModelLegendNode
+     * Draws the symbol of a given symbol QgsLayerTreeModelLegendNode.
      */
     Nucleon drawSymbolItem( QgsLayerTreeModelLegendNode *symbolItem, QPainter *painter = nullptr, QPointF point = QPointF(), double labelXOffset = 0 );
 
     /**
-     * Displays the title of a layer given the QgsLayerTreeLayer, a painter and QPointF
+     * Draws the title of a layer, given a QgsLayerTreeLayer, and a destination \a painter.
-     * otherwise return the size the of the title
+     *
+     * Returns the size of the title.
+     *
+     * The \a painter may be nullptr, in which case on the size is calculated and no painting is attempted.
      */
     QSizeF drawLayerTitle( QgsLayerTreeLayer *nodeLayer, QPainter *painter = nullptr, QPointF point = QPointF() );
 
     /**
      * Draws a group item.
-     * Returns list of sizes of layers and groups including this group.
+     * Returns the size of the title.
      */
     QSizeF drawGroupTitle( QgsLayerTreeGroup *nodeGroup, QPainter *painter = nullptr, QPointF point = QPointF() );
 
     /**
-     * displays the legend and return the size of said legend.
+     * Draws the legend using the specified render \a context, and returns the actual size of the legend.
-     * If QgsRenderContext is null, only the size will be given.
+     *
+     * If \a context is nullptr, only the size of the legend will be calculated and no
+     * painting will be attempted.
      */
-    QSizeF paintAndDetermineSize( QgsRenderContext *rendercontext );
+    QSizeF paintAndDetermineSize( QgsRenderContext *context );
 
     /**
-     * Draws title in the legend using the title font and the specified alignment
+     * Draws a title in the legend using the specified render \a context, with the title font and the specified alignment settings.
-     * If no rendercontext is specified, function returns the required width/height to draw the title.
+     *
+     * Returns the size required to draw the complete title.
+     *
+     * If \a context is nullptr, no painting will be attempted, but the required size will still be calculated and returned.
      */
-    QSizeF drawTitle( QgsRenderContext *rendercontext, QPointF point = QPointF(), Qt::AlignmentFlag halignment = Qt::AlignLeft, double legendWidth = 0 );
+    QSizeF drawTitle( QgsRenderContext *context, QPointF point = QPointF(), Qt::AlignmentFlag halignment = Qt::AlignLeft, double legendWidth = 0 );
 
     /**
-     * Draw atom and return its actual size, the atom is drawn with the space above it
+     * Draws an \a atom and return its actual size, using the specified render \a context.
-     *  so that first atoms in column are all aligned to the same line regardles their
+     *
-     * style top space */
+     * The \a atom is drawn with the space above it, so that the first atoms in column are all
+     * aligned to the same line regardless of their style top spacing.
+     *
+     * If \a context is nullptr, no painting will be attempted, but the required size will still be calculated and returned.
+    */
     QSizeF drawAtom( const Atom &atom, QgsRenderContext *rendercontext, QPointF point = QPointF() );
 
     /**
-     * Displays the symbol of a given QgsLayerTreeModelLegendNode
+     * Draws the symbol of a given symbol QgsLayerTreeModelLegendNode, using the specified render \a context.
      */
-    Nucleon drawSymbolItem( QgsLayerTreeModelLegendNode *symbolItem, QgsRenderContext *rendercontext, QPointF point = QPointF(), double labelXOffset = 0 );
+    Nucleon drawSymbolItem( QgsLayerTreeModelLegendNode *symbolItem, QgsRenderContext *context, QPointF point = QPointF(), double labelXOffset = 0 );
 
     /**
-     * Displays the title of a layer given the QgsLayerTreeLayer, a rendercontext and QPointF
+     * Draws the title of a layer, given a QgsLayerTreeLayer, and a destination render \a context.
-     * otherwise return the size the of the title
+     *
+     * Returns the size of the title.
+     *
+     * The \a context may be nullptr, in which case on the size is calculated and no painting is attempted.
      */
-    QSizeF drawLayerTitle( QgsLayerTreeLayer *nodeLayer, QgsRenderContext *rendercontext, QPointF point = QPointF() );
+    QSizeF drawLayerTitle( QgsLayerTreeLayer *nodeLayer, QgsRenderContext *context, QPointF point = QPointF() );
 
     /**
-     * Draws a group item.
+     * Draws a group's title, using the specified render \a context.
-     * Returns list of sizes of layers and groups including this group.
+     *
+     * Returns the size of the title.
      */
-    QSizeF drawGroupTitle( QgsLayerTreeGroup *nodeGroup, QgsRenderContext *rendercontext, QPointF point = QPointF() );
+    QSizeF drawGroupTitle( QgsLayerTreeGroup *nodeGroup, QgsRenderContext *context, QPointF point = QPointF() );
 
     /**
-     * Returns the style of a given QgsLayerTreeNode
+     * Returns the style of the given \a node.
      */
     QgsLegendStyle::Style nodeLegendStyle( QgsLayerTreeNode *node );