Dox, comments

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

@@ -91,6 +91,8 @@ Subclasses should return ``False`` if they do NOT want to visit this particular
 if the node type is QgsStyleEntityVisitorInterface.NodeType.Layouts and they do not wish to visit
 layout objects. In this case the visitor will not process the node, and will move to the next available
 node instead. Return ``True`` to proceed with visiting the node.
+
+The default implementation returns ``True``.
 %End
 
     virtual bool visitExit( const QgsStyleEntityVisitorInterface::Node &node );
@@ -99,6 +101,8 @@ Called when the visitor stops visiting a ``node``.
 
 Subclasses should return ``False`` to abort further visitations, or ``True`` to continue
 visiting other nodes.
+
+The default implementation returns ``True``.
 %End
 
 };

src/core/annotations/qgsannotation.cpp

@@ -184,6 +184,7 @@ void QgsAnnotation::setAssociatedFeature( const QgsFeature &feature )
 
 bool QgsAnnotation::accept( QgsStyleEntityVisitorInterface *visitor ) const
 {
+  // NOTE: if visitEnter returns false it means "don't visit the annotation", not "abort all further visitations"
   if ( !visitor->visitEnter( QgsStyleEntityVisitorInterface::Node( QgsStyleEntityVisitorInterface::NodeType::Annotation, QStringLiteral( "annotation" ), tr( "Annotation" ) ) ) )
     return true;
 

src/core/annotations/qgsannotationmanager.cpp

@@ -149,6 +149,7 @@ bool QgsAnnotationManager::accept( QgsStyleEntityVisitorInterface *visitor ) con
   if ( mAnnotations.empty() )
     return true;
 
+  // NOTE: if visitEnter returns false it means "don't visit any annotations", not "abort all further visitations"
   if ( !visitor->visitEnter( QgsStyleEntityVisitorInterface::Node( QgsStyleEntityVisitorInterface::NodeType::Annotations, QStringLiteral( "annotations" ), tr( "Annotations" ) ) ) )
     return true;
 

src/core/layout/qgsabstractreportsection.cpp

@@ -173,11 +173,13 @@ void QgsAbstractReportSection::reloadSettings()
 
 bool QgsAbstractReportSection::accept( QgsStyleEntityVisitorInterface *visitor ) const
 {
+  // NOTE: if visitEnter returns false it means "don't visit the report section", not "abort all further visitations"
   if ( mParent && !visitor->visitEnter( QgsStyleEntityVisitorInterface::Node( QgsStyleEntityVisitorInterface::NodeType::ReportSection, QStringLiteral( "reportsection" ), QObject::tr( "Report Section" ) ) ) )
     return true;
 
   if ( mHeader )
   {
+    // NOTE: if visitEnter returns false it means "don't visit the header", not "abort all further visitations"
     if ( visitor->visitEnter( QgsStyleEntityVisitorInterface::Node( QgsStyleEntityVisitorInterface::NodeType::ReportHeader, QStringLiteral( "reportheader" ), QObject::tr( "Report Header" ) ) ) )
     {
       if ( !mHeader->accept( visitor ) )
@@ -196,9 +198,9 @@ bool QgsAbstractReportSection::accept( QgsStyleEntityVisitorInterface *visitor )
 
   if ( mFooter )
   {
+    // NOTE: if visitEnter returns false it means "don't visit the footer", not "abort all further visitations"
     if ( visitor->visitEnter( QgsStyleEntityVisitorInterface::Node( QgsStyleEntityVisitorInterface::NodeType::ReportFooter, QStringLiteral( "reportfooter" ), QObject::tr( "Report Footer" ) ) ) )
     {
-
       if ( !mFooter->accept( visitor ) )
         return false;
 

src/core/layout/qgslayoutitemmap.cpp

@@ -1345,6 +1345,7 @@ bool QgsLayoutItemMap::isLabelBlockingItem( QgsLayoutItem *item ) const
 
 bool QgsLayoutItemMap::accept( QgsStyleEntityVisitorInterface *visitor ) const
 {
+  // NOTE: if visitEnter returns false it means "don't visit the item", not "abort all further visitations"
   if ( !visitor->visitEnter( QgsStyleEntityVisitorInterface::Node( QgsStyleEntityVisitorInterface::NodeType::LayoutItem, uuid(), displayName() ) ) )
     return true;
 

src/core/layout/qgslayoutmanager.cpp

@@ -309,6 +309,7 @@ bool QgsLayoutManager::accept( QgsStyleEntityVisitorInterface *visitor ) const
   if ( mLayouts.empty() )
     return true;
 
+  // NOTE: if visitEnter returns false it means "don't visit the layouts", not "abort all further visitations"
   if ( !visitor->visitEnter( QgsStyleEntityVisitorInterface::Node( QgsStyleEntityVisitorInterface::NodeType::Layouts, QStringLiteral( "layouts" ), tr( "Layouts" ) ) ) )
     return true;
 

src/core/layout/qgsprintlayout.cpp

@@ -116,8 +116,10 @@ void QgsPrintLayout::updateSettings()
 
 bool QgsPrintLayout::layoutAccept( QgsStyleEntityVisitorInterface *visitor ) const
 {
+  // NOTE: if visitEnter returns false it means "don't visit the layout", not "abort all further visitations"
   if ( !visitor->visitEnter( QgsStyleEntityVisitorInterface::Node( QgsStyleEntityVisitorInterface::NodeType::PrintLayout, QStringLiteral( "layout" ), mName ) ) )
     return true;
+
   if ( !accept( visitor ) )
     return false;
   if ( !visitor->visitExit( QgsStyleEntityVisitorInterface::Node( QgsStyleEntityVisitorInterface::NodeType::PrintLayout, QStringLiteral( "layout" ), mName ) ) )

src/core/qgsproject.cpp

@@ -3078,6 +3078,7 @@ bool QgsProject::accept( QgsStyleEntityVisitorInterface *visitor ) const
   {
     for ( auto it = layers.constBegin(); it != layers.constEnd(); ++it )
     {
+      // NOTE: if visitEnter returns false it means "don't visit this layer", not "abort all further visitations"
       if ( visitor->visitEnter( QgsStyleEntityVisitorInterface::Node( QgsStyleEntityVisitorInterface::NodeType::Layer, ( *it )->id(), ( *it )->name() ) ) )
       {
         if ( !( ( *it )->accept( visitor ) ) )

src/core/qgsrulebasedlabeling.cpp

@@ -135,6 +135,7 @@ bool QgsRuleBasedLabeling::Rule::requiresAdvancedEffects() const
 
 bool QgsRuleBasedLabeling::Rule::accept( QgsStyleEntityVisitorInterface *visitor ) const
 {
+  // NOTE: if visitEnter returns false it means "don't visit the rule", not "abort all further visitations"
   if ( mParent && !visitor->visitEnter( QgsStyleEntityVisitorInterface::Node( QgsStyleEntityVisitorInterface::NodeType::SymbolRule, mRuleKey, mDescription ) ) )
     return true;
 

src/core/symbology/qgsrulebasedrenderer.cpp

@@ -158,6 +158,7 @@ void QgsRuleBasedRenderer::Rule::setIsElse( bool iselse )
 
 bool QgsRuleBasedRenderer::Rule::accept( QgsStyleEntityVisitorInterface *visitor ) const
 {
+  // NOTE: if visitEnter returns false it means "don't visit the rule", not "abort all further visitations"
   if ( mParent && !visitor->visitEnter( QgsStyleEntityVisitorInterface::Node( QgsStyleEntityVisitorInterface::NodeType::SymbolRule, mRuleKey, mLabel ) ) )
     return true;
 

src/core/symbology/qgsstyleentityvisitor.h

@@ -78,16 +78,22 @@ class CORE_EXPORT QgsStyleEntityVisitorInterface
        *
        * This may be blank if no identifier is required, e.g. when a renderer has a single
        * symbol only.
+       *
+       * Note that in some cases where a specific identifier is not available, a generic, untranslated
+       * one may be used (e.g. "overview", "grid").
        */
       QString identifier;
 
       /**
        * A string describing the style entity. The actual value of \a description will vary
        * depending on the class being visited. E.g for a categorized renderer, the
-       * description will be the category label associated with the symbol.
+       * description will be the category label associated with the symbol, for a print layout, it will
+       * be the name of the layout in the project.
        *
        * This may be blank if no description is associated with a style entity, e.g. when a renderer has a single
        * symbol only.
+       *
+       * This value may be a generic, translated value in some cases, e.g. "Grid" or "Overview".
        */
       QString description;
 
@@ -144,7 +150,11 @@ class CORE_EXPORT QgsStyleEntityVisitorInterface
      * Subclasses should return FALSE to abort further visitations, or TRUE to continue
      * visiting after processing this entity.
      */
-    virtual bool visit( const QgsStyleEntityVisitorInterface::StyleLeaf &entity ) { Q_UNUSED( entity ); return true; }
+    virtual bool visit( const QgsStyleEntityVisitorInterface::StyleLeaf &entity )
+    {
+      Q_UNUSED( entity )
+      return true;
+    }
 
     /**
      * Called when the visitor starts visiting a \a node.
@@ -153,16 +163,28 @@ class CORE_EXPORT QgsStyleEntityVisitorInterface
      * if the node type is QgsStyleEntityVisitorInterface::NodeType::Layouts and they do not wish to visit
      * layout objects. In this case the visitor will not process the node, and will move to the next available
      * node instead. Return TRUE to proceed with visiting the node.
+     *
+     * The default implementation returns TRUE.
      */
-    virtual bool visitEnter( const QgsStyleEntityVisitorInterface::Node &node ) { Q_UNUSED( node ); return true; }
+    virtual bool visitEnter( const QgsStyleEntityVisitorInterface::Node &node )
+    {
+      Q_UNUSED( node )
+      return true;
+    }
 
     /**
      * Called when the visitor stops visiting a \a node.
      *
      * Subclasses should return FALSE to abort further visitations, or TRUE to continue
      * visiting other nodes.
+     *
+     * The default implementation returns TRUE.
      */
-    virtual bool visitExit( const QgsStyleEntityVisitorInterface::Node &node ) { Q_UNUSED( node ); return true; }
+    virtual bool visitExit( const QgsStyleEntityVisitorInterface::Node &node )
+    {
+      Q_UNUSED( node )
+      return true;
+    }
 
 };