diff --git a/python/core/auto_generated/qgsfeaturesource.sip.in b/python/core/auto_generated/qgsfeaturesource.sip.in
index 88fec47de82..1f6d7336984 100644
--- a/python/core/auto_generated/qgsfeaturesource.sip.in
+++ b/python/core/auto_generated/qgsfeaturesource.sip.in
@@ -22,6 +22,7 @@ An interface for objects which provide features via a getFeatures method.
 #include "qgsfeaturesource.h"
 %End
   public:
+
     enum FeatureAvailability
     {
       NoFeaturesAvailable,
diff --git a/python/core/auto_generated/qgsvectorlayer.sip.in b/python/core/auto_generated/qgsvectorlayer.sip.in
index f412e163c2d..6d2c9210f69 100644
--- a/python/core/auto_generated/qgsvectorlayer.sip.in
+++ b/python/core/auto_generated/qgsvectorlayer.sip.in
@@ -946,13 +946,12 @@ Determines if this vector layer has features.
 
 .. warning::
 
-   A layer is considered empty if neither the data provider nor
-   the edit buffer have features in them.
-   This means the returned value may be inaccurate for layers with unsaved changes,
-   i.e. in the case of all features from the data provider having been
-   deleted within the edit buffer.
+   when a layer is editable and some features
+   have been deleted, this will return
+   QgsFeatureSource.FeatureAvailability.FeaturesMayBeAvailable
+   to avoid a potentially expensive call to the dataprovider.
 
-.. versionadded:: 3.2
+.. versionadded:: 3.4
 %End
 
  void setDataSource( const QString &dataSource, const QString &baseName, const QString &provider, bool loadDefaultStyleFlag = false ) /Deprecated/;
diff --git a/src/core/qgsfeaturesource.h b/src/core/qgsfeaturesource.h
index bf1b5a463ec..5ec08c63673 100644
--- a/src/core/qgsfeaturesource.h
+++ b/src/core/qgsfeaturesource.h
@@ -37,6 +37,16 @@ class QgsFeedback;
 class CORE_EXPORT QgsFeatureSource
 {
   public:
+
+    /**
+     * Return value for hasFeatures() to determine if a source is empty.
+     * It is implemented as a three-value logic, so it can return if
+     * there are features available for sure, if there are no features
+     * available for sure or if there might be features available but
+     * there is no guarantee for this.
+     *
+     * \since QGIS 3.4
+     */
     enum FeatureAvailability
     {
       NoFeaturesAvailable, //!< There are certainly no features available in this source
diff --git a/src/core/qgsvectorlayer.h b/src/core/qgsvectorlayer.h
index baf69d98b2e..f8b087cf073 100644
--- a/src/core/qgsvectorlayer.h
+++ b/src/core/qgsvectorlayer.h
@@ -932,13 +932,12 @@ class CORE_EXPORT QgsVectorLayer : public QgsMapLayer, public QgsExpressionConte
     /**
      * Determines if this vector layer has features.
      *
-     * \warning A layer is considered empty if neither the data provider nor
-     * the edit buffer have features in them.
-     * This means the returned value may be inaccurate for layers with unsaved changes,
-     * i.e. in the case of all features from the data provider having been
-     * deleted within the edit buffer.
+     * \warning when a layer is editable and some features
+     * have been deleted, this will return
+     * QgsFeatureSource::FeatureAvailability::FeaturesMayBeAvailable
+     * to avoid a potentially expensive call to the dataprovider.
      *
-     * \since QGIS 3.2
+     * \since QGIS 3.4
      */
     FeatureAvailability hasFeatures() const override;
 
diff --git a/src/providers/postgres/qgspostgresprovider.h b/src/providers/postgres/qgspostgresprovider.h
index 2c554283d6e..79a9cf0069b 100644
--- a/src/providers/postgres/qgspostgresprovider.h
+++ b/src/providers/postgres/qgspostgresprovider.h
@@ -115,7 +115,7 @@ class QgsPostgresProvider : public QgsVectorDataProvider
      * \note In contrast to the featureCount() method, this method is not
      *       affected by estimated metadata.
      *
-     * \since QGIS 3.2
+     * \since QGIS 3.4
      */
     bool empty() const override;