Dox

python/core/auto_generated/callouts/qgscallout.sip.in

@@ -185,6 +185,9 @@ Any existing properties will be discarded.
 %End
 
     static QgsPropertiesDefinition propertyDefinitions();
+%Docstring
+Returns the definitions for data defined properties available for use in callouts.
+%End
 
   protected:
 
@@ -247,8 +250,21 @@ QgsSimpleLineCallout.properties() ).
 
 
     QgsLineSymbol *lineSymbol();
+%Docstring
+Returns the line symbol used to render the callout line.
+
+Ownership is not transferred.
+
+.. seealso:: :py:func:`setLineSymbol`
+%End
 
     void setLineSymbol( QgsLineSymbol *symbol /Transfer/ );
+%Docstring
+Sets the line ``symbol`` used to render the callout line. Ownership of ``symbol`` is
+transferred to the callout.
+
+.. seealso:: :py:func:`lineSymbol`
+%End
 
     double minimumLength() const;
 %Docstring
@@ -320,6 +336,11 @@ Returns the map unit scale for the minimum callout length.
 
 class QgsManhattanLineCallout : QgsSimpleLineCallout
 {
+%Docstring
+Draws straight (right angled) lines as callouts.
+
+.. versionadded:: 3.10
+%End
 
 %TypeHeaderCode
 #include "qgscallout.h"

python/core/auto_generated/callouts/qgscalloutsregistry.sip.in

@@ -20,14 +20,20 @@ Stores metadata about one callout renderer class.
    It's necessary to implement createCallout() function.
    In C++ you can use QgsCalloutMetadata convenience class.
 
-\sincce QGIS 3.10
+.. versionadded:: 3.10
 %End
 
 %TypeHeaderCode
 #include "qgscalloutsregistry.h"
 %End
   public:
+
     QgsCalloutAbstractMetadata( const QString &name, const QString &visibleName );
+%Docstring
+Constructor for QgsCalloutAbstractMetadata, with the specified ``name``.
+
+The ``visibleName`` argument gives a translated, user friendly string identifying the callout type.
+%End
 
     virtual ~QgsCalloutAbstractMetadata();
 

python/gui/auto_generated/callouts/qgscalloutwidget.sip.in

@@ -10,6 +10,11 @@
 
 class QgsCalloutWidget : QWidget, protected QgsExpressionContextGenerator
 {
+%Docstring
+Base class for widgets which allow control over the properties of callouts.
+
+.. versionadded:: 3.10
+%End
 
 %TypeHeaderCode
 #include "qgscalloutwidget.h"
@@ -25,7 +30,19 @@ Constructor for QgsCalloutWidget.
 %End
 
     virtual void setCallout( QgsCallout *callout ) = 0;
+%Docstring
+Sets the ``callout`` to show in the widget. Ownership is not transferred.
+
+.. seealso:: :py:func:`callout`
+%End
+
     virtual QgsCallout *callout() = 0;
+%Docstring
+Returns the callout defined by the current settings in the widget. Ownership is not transferred,
+and the caller should clone the returned value.
+
+.. seealso:: :py:func:`setCallout`
+%End
 
     virtual void setContext( const QgsSymbolWidgetContext &context );
 %Docstring
@@ -74,9 +91,6 @@ Should be emitted whenever configuration changes happened on this symbol layer c
 If the subsymbol is changed, symbolChanged() should be emitted instead.
 %End
 
-  protected slots:
-    void updateDataDefinedProperty();
-
 };
 
 

src/core/callouts/qgscallout.h

@@ -198,6 +198,9 @@ class CORE_EXPORT QgsCallout
      */
     void setDataDefinedProperties( const QgsPropertyCollection &collection ) { mDataDefinedProperties = collection; }
 
+    /**
+     * Returns the definitions for data defined properties available for use in callouts.
+     */
     static QgsPropertiesDefinition propertyDefinitions();
 
   protected:
@@ -246,6 +249,10 @@ class CORE_EXPORT QgsSimpleLineCallout : public QgsCallout
     ~QgsSimpleLineCallout() override;
 
 #ifndef SIP_RUN
+
+    /**
+     * Copy constructor.
+     */
     QgsSimpleLineCallout( const QgsSimpleLineCallout &other );
     QgsSimpleLineCallout &operator=( const QgsSimpleLineCallout & ) = delete;
 #endif
@@ -265,8 +272,21 @@ class CORE_EXPORT QgsSimpleLineCallout : public QgsCallout
     void stopRender( QgsRenderContext &context ) override;
     QSet< QString > referencedFields( const QgsRenderContext &context ) const override;
 
+    /**
+     * Returns the line symbol used to render the callout line.
+     *
+     * Ownership is not transferred.
+     *
+     * \see setLineSymbol()
+     */
     QgsLineSymbol *lineSymbol();
 
+    /**
+     * Sets the line \a symbol used to render the callout line. Ownership of \a symbol is
+     * transferred to the callout.
+     *
+     * \see lineSymbol()
+     */
     void setLineSymbol( QgsLineSymbol *symbol SIP_TRANSFER );
 
     /**
@@ -330,6 +350,12 @@ class CORE_EXPORT QgsSimpleLineCallout : public QgsCallout
 };
 
 
+/**
+ * \ingroup core
+ * \brief Draws straight (right angled) lines as callouts.
+ *
+ * \since QGIS 3.10
+ */
 class CORE_EXPORT QgsManhattanLineCallout : public QgsSimpleLineCallout
 {
   public:
@@ -337,7 +363,12 @@ class CORE_EXPORT QgsManhattanLineCallout : public QgsSimpleLineCallout
     QgsManhattanLineCallout();
 
 #ifndef SIP_RUN
+
+    /**
+     * Copy constructor.
+     */
     QgsManhattanLineCallout( const QgsManhattanLineCallout &other );
+
     QgsManhattanLineCallout &operator=( const QgsManhattanLineCallout & ) = delete;
 #endif
 

src/core/callouts/qgscalloutsregistry.h

@@ -33,11 +33,17 @@ class QDomElement;
  *  \note It's necessary to implement createCallout() function.
  *  In C++ you can use QgsCalloutMetadata convenience class.
  *
- *  \sincce QGIS 3.10
+ *  \since QGIS 3.10
  */
 class CORE_EXPORT QgsCalloutAbstractMetadata
 {
   public:
+
+    /**
+     * Constructor for QgsCalloutAbstractMetadata, with the specified \a name.
+     *
+     * The \a visibleName argument gives a translated, user friendly string identifying the callout type.
+     */
     QgsCalloutAbstractMetadata( const QString &name, const QString &visibleName )
       : mName( name )
       , mVisibleName( visibleName )

src/gui/callouts/qgscalloutwidget.h

@@ -28,6 +28,8 @@ class QgsMapCanvas;
 /**
  * \ingroup gui
  * \class QgsCalloutWidget
+ * Base class for widgets which allow control over the properties of callouts.
+ * \since QGIS 3.10
  */
 class GUI_EXPORT QgsCalloutWidget : public QWidget, protected QgsExpressionContextGenerator
 {
@@ -45,7 +47,17 @@ class GUI_EXPORT QgsCalloutWidget : public QWidget, protected QgsExpressionConte
       , mVectorLayer( vl )
     {}
 
+    /**
+     * Sets the \a callout to show in the widget. Ownership is not transferred.
+     * \see callout()
+     */
     virtual void setCallout( QgsCallout *callout ) = 0;
+
+    /**
+     * Returns the callout defined by the current settings in the widget. Ownership is not transferred,
+     * and the caller should clone the returned value.
+     * \see setCallout()
+     */
     virtual QgsCallout *callout() = 0;
 
     /**
@@ -93,10 +105,9 @@ class GUI_EXPORT QgsCalloutWidget : public QWidget, protected QgsExpressionConte
      */
     void changed();
 
-  protected slots:
+  private slots:
     void updateDataDefinedProperty();
 
-  private slots:
     void createAuxiliaryField();
 
   private: