diff --git a/src/core/geometry/qgsgeos.cpp b/src/core/geometry/qgsgeos.cpp
index b3bc5b8baec..a1b987b71c3 100644
--- a/src/core/geometry/qgsgeos.cpp
+++ b/src/core/geometry/qgsgeos.cpp
@@ -49,8 +49,7 @@ email                : marco.hugentobler at sourcepole dot com
     return r; \
   }
 
-///@cond
-//not part of public API
+/// @cond PRIVATE
 
 static void throwGEOSException( const char *fmt, ... )
 {
diff --git a/src/core/geometry/qgsgeos.h b/src/core/geometry/qgsgeos.h
index 2fd0f05dd9b..bae295d4d94 100644
--- a/src/core/geometry/qgsgeos.h
+++ b/src/core/geometry/qgsgeos.h
@@ -152,7 +152,7 @@ class CORE_EXPORT QgsGeos: public QgsGeometryEngine
     static int geomDigits( const GEOSGeometry* geom );
 };
 
-/// @cond
+/// @cond PRIVATE
 
 class GEOSException
 {
diff --git a/src/core/qgsdatadefined_p.h b/src/core/qgsdatadefined_p.h
index 14d661b3d0e..d51b9e84891 100644
--- a/src/core/qgsdatadefined_p.h
+++ b/src/core/qgsdatadefined_p.h
@@ -15,7 +15,7 @@
 #ifndef QGSDATADEFINED_PRIVATE_H
 #define QGSDATADEFINED_PRIVATE_H
 
-/// @cond
+/// @cond PRIVATE
 
 //
 //  W A R N I N G
diff --git a/src/core/qgsexpressioncontext.cpp b/src/core/qgsexpressioncontext.cpp
index 1e693427eb6..bb0afa56133 100644
--- a/src/core/qgsexpressioncontext.cpp
+++ b/src/core/qgsexpressioncontext.cpp
@@ -118,8 +118,7 @@ bool QgsExpressionContextScope::variableNameSort( const QString& a, const QStrin
   return QString::localeAwareCompare( a, b ) < 0;
 }
 
-// not public API
-/// @cond
+/// @cond PRIVATE
 class QgsExpressionContextVariableCompare
 {
   public:
@@ -496,8 +495,7 @@ void QgsExpressionContextUtils::setGlobalVariables( const QgsStringMap &variable
   settings.setValue( QString( "/variables/values" ), customVariableVariants );
 }
 
-///@cond
-//not part of public API
+/// @cond PRIVATE
 
 class GetNamedProjectColor : public QgsScopedExpressionFunction
 {
diff --git a/src/core/qgsfeature_p.h b/src/core/qgsfeature_p.h
index 9c2dfb6e2e9..ecc3e568315 100644
--- a/src/core/qgsfeature_p.h
+++ b/src/core/qgsfeature_p.h
@@ -16,7 +16,7 @@ email                : nyall dot dawson at gmail dot com
 #ifndef QGSFEATURE_PRIVATE_H
 #define QGSFEATURE_PRIVATE_H
 
-/// @cond
+/// @cond PRIVATE
 
 //
 //  W A R N I N G
diff --git a/src/core/qgsfeatureiterator.cpp b/src/core/qgsfeatureiterator.cpp
index 43c730f333c..d177ac203a7 100644
--- a/src/core/qgsfeatureiterator.cpp
+++ b/src/core/qgsfeatureiterator.cpp
@@ -21,7 +21,7 @@
 #include <algorithm>
 
 
-/// @cond
+/// @cond PRIVATE
 class QgsExpressionSorter
 {
   public:
diff --git a/src/core/qgsfield_p.h b/src/core/qgsfield_p.h
index 9017677dace..626417b86ec 100644
--- a/src/core/qgsfield_p.h
+++ b/src/core/qgsfield_p.h
@@ -16,7 +16,7 @@
 #ifndef QGSFIELD_PRIVATE_H
 #define QGSFIELD_PRIVATE_H
 
-/// @cond
+/// @cond PRIVATE
 
 //
 //  W A R N I N G
diff --git a/src/core/qgsnetworkaccessmanager.cpp b/src/core/qgsnetworkaccessmanager.cpp
index 5cb0f7f5fd2..8e0f41175d3 100644
--- a/src/core/qgsnetworkaccessmanager.cpp
+++ b/src/core/qgsnetworkaccessmanager.cpp
@@ -38,8 +38,7 @@
 
 #include "qgsauthmanager.h"
 
-//not part of public API
-///@cond
+/// @cond PRIVATE
 //! @note not available in Python bindings
 class QgsNetworkProxyFactory : public QNetworkProxyFactory
 {
diff --git a/src/core/qgswebframe.h b/src/core/qgswebframe.h
index 01ebb229524..9f88fdb32b2 100644
--- a/src/core/qgswebframe.h
+++ b/src/core/qgswebframe.h
@@ -30,7 +30,7 @@
  */
 class CORE_EXPORT QWebFrame : public QObject
 {
-/// @cond
+/// @cond NOT_STABLE_API
     Q_OBJECT
 
   public:
diff --git a/src/core/qgswebpage.h b/src/core/qgswebpage.h
index 5f86bab18a8..c5de9dc2e94 100644
--- a/src/core/qgswebpage.h
+++ b/src/core/qgswebpage.h
@@ -35,7 +35,7 @@
  */
 class CORE_EXPORT QWebSettings : public QObject
 {
-/// @cond
+/// @cond NOT_STABLE_API
     Q_OBJECT
 
   public:
@@ -98,7 +98,7 @@ class CORE_EXPORT QWebSettings : public QObject
  */
 class CORE_EXPORT QWebPage : public QObject
 {
-/// @cond
+/// @cond NOT_STABLE_API
     Q_OBJECT
 
   public:
diff --git a/src/core/qgswebview.h b/src/core/qgswebview.h
index 35b6a15316d..61d399041f8 100644
--- a/src/core/qgswebview.h
+++ b/src/core/qgswebview.h
@@ -54,7 +54,7 @@ class CORE_EXPORT QgsWebView : public QWebView
 class CORE_EXPORT QgsWebView : public QWidget
 {
 
-/// @cond
+/// @cond NOT_STABLE_API
     Q_OBJECT
   public:
     explicit QgsWebView( QWidget *parent = 0 )
diff --git a/src/core/symbology-ng/qgslinesymbollayerv2.cpp b/src/core/symbology-ng/qgslinesymbollayerv2.cpp
index 4dbc0e874dc..53e9e43d6c4 100644
--- a/src/core/symbology-ng/qgslinesymbollayerv2.cpp
+++ b/src/core/symbology-ng/qgslinesymbollayerv2.cpp
@@ -649,8 +649,7 @@ double QgsSimpleLineSymbolLayerV2::dxfOffset( const QgsDxfExport& e, QgsSymbolV2
 
 /////////
 
-///@cond
-//not part of public API
+///@cond PRIVATE
 
 class MyLine
 {
diff --git a/src/gui/effects/qgseffectstackpropertieswidget.cpp b/src/gui/effects/qgseffectstackpropertieswidget.cpp
index 24d32633b7f..7f6175fe37d 100644
--- a/src/gui/effects/qgseffectstackpropertieswidget.cpp
+++ b/src/gui/effects/qgseffectstackpropertieswidget.cpp
@@ -29,8 +29,7 @@
 #include <QCheckBox>
 #include <QToolButton>
 
-///@cond
-//not part of public API
+///@cond PRIVATE
 
 static const int EffectItemType = QStandardItem::UserType + 1;
 
diff --git a/src/gui/layertree/qgscustomlayerorderwidget.cpp b/src/gui/layertree/qgscustomlayerorderwidget.cpp
index f990f19e513..b0fcc661d9b 100644
--- a/src/gui/layertree/qgscustomlayerorderwidget.cpp
+++ b/src/gui/layertree/qgscustomlayerorderwidget.cpp
@@ -91,8 +91,7 @@ void QgsCustomLayerOrderWidget::modelUpdated()
 }
 
 
-///@cond
-/// not part of public API
+///@cond PRIVATE
 
 CustomLayerOrderModel::CustomLayerOrderModel( QgsLayerTreeMapCanvasBridge* bridge, QObject* parent )
     : QAbstractListModel( parent ), mBridge( bridge )
diff --git a/src/gui/layertree/qgscustomlayerorderwidget.h b/src/gui/layertree/qgscustomlayerorderwidget.h
index b89d705c69b..909fca90637 100644
--- a/src/gui/layertree/qgscustomlayerorderwidget.h
+++ b/src/gui/layertree/qgscustomlayerorderwidget.h
@@ -60,8 +60,7 @@ class GUI_EXPORT QgsCustomLayerOrderWidget : public QWidget
 };
 
 
-///@cond
-//not part of public API
+///@cond PRIVATE
 class CustomLayerOrderModel : public QAbstractListModel
 {
     Q_OBJECT
diff --git a/src/gui/qgsidentifymenu.cpp b/src/gui/qgsidentifymenu.cpp
index 607e4e77a87..43230972dd7 100644
--- a/src/gui/qgsidentifymenu.cpp
+++ b/src/gui/qgsidentifymenu.cpp
@@ -22,7 +22,7 @@
 #include "qgshighlight.h"
 
 
-///@cond
+/// @cond PRIVATE
 CustomActionRegistry::CustomActionRegistry( QObject* parent )
     : QgsMapLayerActionRegistry( parent )
 {
diff --git a/src/gui/qgsidentifymenu.h b/src/gui/qgsidentifymenu.h
index a7e86da56d6..56ad480bfdc 100644
--- a/src/gui/qgsidentifymenu.h
+++ b/src/gui/qgsidentifymenu.h
@@ -23,8 +23,7 @@
 #include "qgsmaptoolidentify.h"
 #include "qgsvectorlayer.h"
 
-// not part of public API
-///@cond
+/// @cond PRIVATE
 //! @note not available in Python bindings
 class CustomActionRegistry : public QgsMapLayerActionRegistry
 {
diff --git a/src/gui/qgsmapmouseevent.cpp b/src/gui/qgsmapmouseevent.cpp
index 68dd7b8f5e1..3c9844129f2 100644
--- a/src/gui/qgsmapmouseevent.cpp
+++ b/src/gui/qgsmapmouseevent.cpp
@@ -19,7 +19,7 @@
 
 #include "qgssnappingutils.h"
 
-/// @cond
+/// @cond PRIVATE
 struct EdgesOnlyFilter : public QgsPointLocator::MatchFilter
 {
   bool acceptMatch( const QgsPointLocator::Match& m ) override { return m.hasEdge(); }
diff --git a/src/gui/qgsmapoverviewcanvas.cpp b/src/gui/qgsmapoverviewcanvas.cpp
index f68fe11d682..a17bf81967e 100644
--- a/src/gui/qgsmapoverviewcanvas.cpp
+++ b/src/gui/qgsmapoverviewcanvas.cpp
@@ -268,7 +268,7 @@ QStringList QgsMapOverviewCanvas::layerSet() const
 }
 
 
-///@cond
+/// @cond PRIVATE
 
 QgsPanningWidget::QgsPanningWidget( QWidget* parent )
     : QWidget( parent )
diff --git a/src/gui/qgsmapoverviewcanvas.h b/src/gui/qgsmapoverviewcanvas.h
index 45e5e0d4ec4..e0839c2d4cb 100644
--- a/src/gui/qgsmapoverviewcanvas.h
+++ b/src/gui/qgsmapoverviewcanvas.h
@@ -116,8 +116,7 @@ class GUI_EXPORT QgsMapOverviewCanvas : public QWidget
 };
 
 
-// not part of public API
-///@cond
+/// @cond PRIVATE
 //! Widget that serves as rectangle showing current extent in overview
 //! @note not available in Python bindings
 class QgsPanningWidget : public QWidget
diff --git a/src/gui/qgsvariableeditorwidget.cpp b/src/gui/qgsvariableeditorwidget.cpp
index f86703ea8da..a05b4feb400 100644
--- a/src/gui/qgsvariableeditorwidget.cpp
+++ b/src/gui/qgsvariableeditorwidget.cpp
@@ -242,7 +242,7 @@ void QgsVariableEditorWidget::selectionChanged()
 }
 
 
-/// @cond
+/// @cond PRIVATE
 //
 // VariableEditorTree
 //
diff --git a/src/gui/qgsvariableeditorwidget.h b/src/gui/qgsvariableeditorwidget.h
index 0de991bab04..f50ecb3565c 100644
--- a/src/gui/qgsvariableeditorwidget.h
+++ b/src/gui/qgsvariableeditorwidget.h
@@ -138,7 +138,7 @@ class GUI_EXPORT QgsVariableEditorWidget : public QWidget
 };
 
 
-/// @cond
+/// @cond PRIVATE
 
 /* QgsVariableEditorTree is NOT part of the public QGIS api. It's only
  * public here as Qt meta objects can't be nested classes
diff --git a/src/gui/symbology-ng/qgscategorizedsymbolrendererv2widget.cpp b/src/gui/symbology-ng/qgscategorizedsymbolrendererv2widget.cpp
index abf15febd1e..b35b23c2e65 100644
--- a/src/gui/symbology-ng/qgscategorizedsymbolrendererv2widget.cpp
+++ b/src/gui/symbology-ng/qgscategorizedsymbolrendererv2widget.cpp
@@ -40,8 +40,7 @@
 #include <QPainter>
 #include <QFileDialog>
 
-///@cond
-//not part of public API
+///@cond PRIVATE
 
 QgsCategorizedSymbolRendererV2Model::QgsCategorizedSymbolRendererV2Model( QObject * parent ) : QAbstractItemModel( parent )
     , mRenderer( nullptr )
diff --git a/src/gui/symbology-ng/qgscategorizedsymbolrendererv2widget.h b/src/gui/symbology-ng/qgscategorizedsymbolrendererv2widget.h
index 7cb6a062c53..31f5b9b6a45 100644
--- a/src/gui/symbology-ng/qgscategorizedsymbolrendererv2widget.h
+++ b/src/gui/symbology-ng/qgscategorizedsymbolrendererv2widget.h
@@ -25,8 +25,7 @@ class QgsRendererCategoryV2;
 
 #include "ui_qgscategorizedsymbolrendererv2widget.h"
 
-///@cond
-//not part of public API
+///@cond PRIVATE
 
 class GUI_EXPORT QgsCategorizedSymbolRendererV2Model : public QAbstractItemModel
 {
diff --git a/src/gui/symbology-ng/qgscptcitycolorrampv2dialog.cpp b/src/gui/symbology-ng/qgscptcitycolorrampv2dialog.cpp
index f62cb009850..d7d8c67b690 100644
--- a/src/gui/symbology-ng/qgscptcitycolorrampv2dialog.cpp
+++ b/src/gui/symbology-ng/qgscptcitycolorrampv2dialog.cpp
@@ -688,7 +688,7 @@ void QgsCptCityColorRampV2Dialog::refreshModel( const QModelIndex& index )
 }
 #endif
 
-///@cond
+/// @cond PRIVATE
 
 TreeFilterProxyModel::TreeFilterProxyModel( QObject* parent, QgsCptCityBrowserModel* model )
     : QSortFilterProxyModel( parent ), mModel( model )
diff --git a/src/gui/symbology-ng/qgscptcitycolorrampv2dialog.h b/src/gui/symbology-ng/qgscptcitycolorrampv2dialog.h
index 11f786c6c08..81c89c42466 100644
--- a/src/gui/symbology-ng/qgscptcitycolorrampv2dialog.h
+++ b/src/gui/symbology-ng/qgscptcitycolorrampv2dialog.h
@@ -83,8 +83,7 @@ class GUI_EXPORT QgsCptCityColorRampV2Dialog : public QDialog, private Ui::QgsCp
 
 };
 
-///@cond
-//not part of public API
+/// @cond PRIVATE
 
 class TreeFilterProxyModel : public QSortFilterProxyModel
 {
diff --git a/src/gui/symbology-ng/qgsgraduatedhistogramwidget.cpp b/src/gui/symbology-ng/qgsgraduatedhistogramwidget.cpp
index 0147b9912d4..0f6ece4c7f4 100644
--- a/src/gui/symbology-ng/qgsgraduatedhistogramwidget.cpp
+++ b/src/gui/symbology-ng/qgsgraduatedhistogramwidget.cpp
@@ -180,7 +180,7 @@ void QgsGraduatedHistogramWidget::findClosestRange( double value, int &closestRa
   }
 }
 
-///@cond
+/// @cond PRIVATE
 
 QgsGraduatedHistogramEventFilter::QgsGraduatedHistogramEventFilter( QwtPlot *plot )
     : QObject( plot )
diff --git a/src/gui/symbology-ng/qgsgraduatedhistogramwidget.h b/src/gui/symbology-ng/qgsgraduatedhistogramwidget.h
index e8fc99074c5..7ddefa3f4a0 100644
--- a/src/gui/symbology-ng/qgsgraduatedhistogramwidget.h
+++ b/src/gui/symbology-ng/qgsgraduatedhistogramwidget.h
@@ -87,7 +87,7 @@ class GUI_EXPORT QgsGraduatedHistogramWidget : public QgsHistogramWidget
 // For private use by QgsGraduatedHistogramWidget only,
 // not part of stable api or exposed to Python bindings
 //
-///@cond
+/// @cond PRIVATE
 class GUI_EXPORT QgsGraduatedHistogramEventFilter: public QObject
 {
     Q_OBJECT
diff --git a/src/gui/symbology-ng/qgsgraduatedsymbolrendererv2widget.cpp b/src/gui/symbology-ng/qgsgraduatedsymbolrendererv2widget.cpp
index ae7f9404bb3..e40f170141e 100644
--- a/src/gui/symbology-ng/qgsgraduatedsymbolrendererv2widget.cpp
+++ b/src/gui/symbology-ng/qgsgraduatedsymbolrendererv2widget.cpp
@@ -39,8 +39,7 @@
 
 // ------------------------------ Model ------------------------------------
 
-///@cond
-//not part of public API
+///@cond PRIVATE
 
 QgsGraduatedSymbolRendererV2Model::QgsGraduatedSymbolRendererV2Model( QObject * parent ) : QAbstractItemModel( parent )
     , mRenderer( nullptr )
diff --git a/src/gui/symbology-ng/qgsgraduatedsymbolrendererv2widget.h b/src/gui/symbology-ng/qgsgraduatedsymbolrendererv2widget.h
index 97b4eb4facd..9c8cc0a3b66 100644
--- a/src/gui/symbology-ng/qgsgraduatedsymbolrendererv2widget.h
+++ b/src/gui/symbology-ng/qgsgraduatedsymbolrendererv2widget.h
@@ -23,8 +23,7 @@
 
 #include "ui_qgsgraduatedsymbolrendererv2widget.h"
 
-///@cond
-//not part of public API
+/// @cond PRIVATE
 
 class GUI_EXPORT QgsGraduatedSymbolRendererV2Model : public QAbstractItemModel
 {
diff --git a/src/gui/symbology-ng/qgssizescalewidget.cpp b/src/gui/symbology-ng/qgssizescalewidget.cpp
index 92f7ecbbfbb..0472e6355f9 100644
--- a/src/gui/symbology-ng/qgssizescalewidget.cpp
+++ b/src/gui/symbology-ng/qgssizescalewidget.cpp
@@ -32,8 +32,7 @@
 
 #include <limits>
 
-///@cond
-//not part of public API
+///@cond PRIVATE
 
 // RAII class to block a QObject signal until destroyed
 struct SignalBlocker
diff --git a/src/gui/symbology-ng/qgssizescalewidget.h b/src/gui/symbology-ng/qgssizescalewidget.h
index a9c84caeecd..58bb01bbfa8 100644
--- a/src/gui/symbology-ng/qgssizescalewidget.h
+++ b/src/gui/symbology-ng/qgssizescalewidget.h
@@ -67,9 +67,7 @@ class GUI_EXPORT QgsSizeScaleWidget : public QgsDataDefinedAssistant, private Ui
 
 };
 
-
-// not part of public API
-///@cond
+/// @cond PRIVATE
 //! @note not available in Python bindings
 class ItemDelegate : public QItemDelegate
 {
diff --git a/src/gui/symbology-ng/qgssymbollayerv2widget.cpp b/src/gui/symbology-ng/qgssymbollayerv2widget.cpp
index bce83e40660..f34f05d095c 100644
--- a/src/gui/symbology-ng/qgssymbollayerv2widget.cpp
+++ b/src/gui/symbology-ng/qgssymbollayerv2widget.cpp
@@ -2966,7 +2966,7 @@ void QgsRasterFillSymbolLayerWidget::updatePreviewImage()
 }
 
 
-/// @cond
+/// @cond PRIVATE
 
 QgsSvgListModel::QgsSvgListModel( QObject* parent ) : QAbstractListModel( parent )
 {
diff --git a/src/gui/symbology-ng/qgssymbollayerv2widget.h b/src/gui/symbology-ng/qgssymbollayerv2widget.h
index e1786dca16d..9d58b364cb3 100644
--- a/src/gui/symbology-ng/qgssymbollayerv2widget.h
+++ b/src/gui/symbology-ng/qgssymbollayerv2widget.h
@@ -624,8 +624,7 @@ class GUI_EXPORT QgsCentroidFillSymbolLayerV2Widget : public QgsSymbolLayerV2Wid
 };
 
 
-///@cond
-//not part of public API
+///@cond PRIVATE
 
 class QgsSvgListModel : public QAbstractListModel
 {
diff --git a/src/gui/symbology-ng/qgssymbollevelsv2dialog.cpp b/src/gui/symbology-ng/qgssymbollevelsv2dialog.cpp
index f7578ac767c..c8488258eee 100644
--- a/src/gui/symbology-ng/qgssymbollevelsv2dialog.cpp
+++ b/src/gui/symbology-ng/qgssymbollevelsv2dialog.cpp
@@ -164,7 +164,7 @@ void QgsSymbolLevelsV2Dialog::setForceOrderingEnabled( bool enabled )
 }
 
 
-///@cond
+/// @cond PRIVATE
 
 QWidget* SpinBoxDelegate::createEditor( QWidget* parent, const QStyleOptionViewItem&, const QModelIndex& ) const
 {
diff --git a/src/gui/symbology-ng/qgssymbollevelsv2dialog.h b/src/gui/symbology-ng/qgssymbollevelsv2dialog.h
index 3c3181f904d..1c028bd32e0 100644
--- a/src/gui/symbology-ng/qgssymbollevelsv2dialog.h
+++ b/src/gui/symbology-ng/qgssymbollevelsv2dialog.h
@@ -57,8 +57,7 @@ class GUI_EXPORT QgsSymbolLevelsV2Dialog : public QDialog, private Ui::QgsSymbol
     bool mForceOrderingEnabled;
 };
 
-///@cond
-//not part of public API
+///@cond PRIVATE
 
 // delegate used from Qt Spin Box example
 class SpinBoxDelegate : public QItemDelegate
diff --git a/src/gui/symbology-ng/qgssymbolv2selectordialog.cpp b/src/gui/symbology-ng/qgssymbolv2selectordialog.cpp
index 276c11bbe77..5f90d2eff65 100644
--- a/src/gui/symbology-ng/qgssymbolv2selectordialog.cpp
+++ b/src/gui/symbology-ng/qgssymbolv2selectordialog.cpp
@@ -44,8 +44,7 @@
 #include <QFile>
 #include <QStandardItem>
 
-///@cond
-//not part of public API
+/// @cond PRIVATE
 
 static const int SymbolLayerItemType = QStandardItem::UserType + 1;
 
diff --git a/src/gui/symbology-ng/qgssymbolv2selectordialog.h b/src/gui/symbology-ng/qgssymbolv2selectordialog.h
index b34f01f9b39..ced905dfbb7 100644
--- a/src/gui/symbology-ng/qgssymbolv2selectordialog.h
+++ b/src/gui/symbology-ng/qgssymbolv2selectordialog.h
@@ -41,8 +41,8 @@ class QgsLineSymbolLayerV2;
 
 class QgsMapCanvas;
 
-///@cond
-//not part of public API
+/// @cond PRIVATE
+
 class DataDefinedRestorer: public QObject
 {
     Q_OBJECT