diff --git a/python/core/auto_generated/qgsproject.sip.in b/python/core/auto_generated/qgsproject.sip.in
index 1144db936ba..5b3fee16774 100644
--- a/python/core/auto_generated/qgsproject.sip.in
+++ b/python/core/auto_generated/qgsproject.sip.in
@@ -110,7 +110,8 @@ Returns QFileInfo object for the project's associated file.
 .. seealso:: :py:func:`fileName`
 
 .. versionadded:: 2.9
-\deprecated
+
+.. deprecated:: Use absoluteFilePath(), baseName() or lastModifiedTime() instead
 %End
 
     QgsProjectStorage *projectStorage() const;
diff --git a/python/gui/auto_generated/attributetable/qgsfeaturelistmodel.sip.in b/python/gui/auto_generated/attributetable/qgsfeaturelistmodel.sip.in
index d908debf11a..adb6e91e2b6 100644
--- a/python/gui/auto_generated/attributetable/qgsfeaturelistmodel.sip.in
+++ b/python/gui/auto_generated/attributetable/qgsfeaturelistmodel.sip.in
@@ -138,28 +138,28 @@ Sort this model by its display expression.
 %Docstring
 Does nothing except for calling beginRemoveRows()
 
-\deprecated
+.. deprecated:: Use beginRemoveRows() instead
 %End
 
  void onEndRemoveRows( const QModelIndex &parent, int first, int last );
 %Docstring
 Does nothing except for calling endRemoveRows()
 
-\deprecated
+.. deprecated:: Use endRemoveRows() instead
 %End
 
  void onBeginInsertRows( const QModelIndex &parent, int first, int last );
 %Docstring
 Does nothing except for calling beginInsertRows()
 
-\deprecated
+.. deprecated:: use beginInsertRows() instead
 %End
 
  void onEndInsertRows( const QModelIndex &parent, int first, int last );
 %Docstring
 Does nothing except for calling endInsertRows()
 
-\deprecated
+.. deprecated:: use endInsertRows() instead
 %End
 
 };
diff --git a/python/gui/auto_generated/qgisinterface.sip.in b/python/gui/auto_generated/qgisinterface.sip.in
index aa52f8b7176..16611574a67 100644
--- a/python/gui/auto_generated/qgisinterface.sip.in
+++ b/python/gui/auto_generated/qgisinterface.sip.in
@@ -859,7 +859,8 @@ QGIS documentation, set useQgisDocDirectory to false.
 :param url: URL to open
 :param useQgisDocDirectory: If true, the URL will be formed by concatenating
 url to the QGIS documentation directory path (prefix/share/doc)
-\deprecated
+
+.. deprecated:: Use QDesktopServices instead
 %End
 
     virtual bool openFeatureForm( QgsVectorLayer *l, QgsFeature &f, bool updateFeatureOnly = false, bool showModal = true ) = 0;
diff --git a/src/core/qgsproject.h b/src/core/qgsproject.h
index ea139a7b83d..763097e8278 100644
--- a/src/core/qgsproject.h
+++ b/src/core/qgsproject.h
@@ -158,7 +158,7 @@ class CORE_EXPORT QgsProject : public QObject, public QgsExpressionContextGenera
      *
      * \see fileName()
      * \since QGIS 2.9
-     * \deprecated
+     * \deprecated Use absoluteFilePath(), baseName() or lastModifiedTime() instead
      */
     Q_DECL_DEPRECATED QFileInfo fileInfo() const SIP_DEPRECATED;
 
diff --git a/src/gui/attributetable/qgsfeaturelistmodel.h b/src/gui/attributetable/qgsfeaturelistmodel.h
index 88b313f3586..040bedde28d 100644
--- a/src/gui/attributetable/qgsfeaturelistmodel.h
+++ b/src/gui/attributetable/qgsfeaturelistmodel.h
@@ -143,28 +143,28 @@ class GUI_EXPORT QgsFeatureListModel : public QSortFilterProxyModel, public QgsF
     /**
      * Does nothing except for calling beginRemoveRows()
      *
-     * \deprecated
+     * \deprecated Use beginRemoveRows() instead
      */
     Q_DECL_DEPRECATED void onBeginRemoveRows( const QModelIndex &parent, int first, int last );
 
     /**
      * Does nothing except for calling endRemoveRows()
      *
-     * \deprecated
+     * \deprecated Use endRemoveRows() instead
      */
     Q_DECL_DEPRECATED void onEndRemoveRows( const QModelIndex &parent, int first, int last );
 
     /**
      * Does nothing except for calling beginInsertRows()
      *
-     * \deprecated
+     * \deprecated use beginInsertRows() instead
      */
     Q_DECL_DEPRECATED void onBeginInsertRows( const QModelIndex &parent, int first, int last );
 
     /**
      * Does nothing except for calling endInsertRows()
      *
-     * \deprecated
+     * \deprecated use endInsertRows() instead
      */
     Q_DECL_DEPRECATED void onEndInsertRows( const QModelIndex &parent, int first, int last );
 
diff --git a/src/gui/qgisinterface.h b/src/gui/qgisinterface.h
index ee5ce68009c..02eec164679 100644
--- a/src/gui/qgisinterface.h
+++ b/src/gui/qgisinterface.h
@@ -698,7 +698,7 @@ class GUI_EXPORT QgisInterface : public QObject
      * \param url URL to open
      * \param useQgisDocDirectory If true, the URL will be formed by concatenating
      * url to the QGIS documentation directory path (prefix/share/doc)
-     * \deprecated
+     * \deprecated Use QDesktopServices instead
      */
 #ifndef Q_MOC_RUN
     Q_DECL_DEPRECATED
diff --git a/tests/code_layout/doxygen_parser.py b/tests/code_layout/doxygen_parser.py
index 36d33c1dbc5..1cd94834ebd 100644
--- a/tests/code_layout/doxygen_parser.py
+++ b/tests/code_layout/doxygen_parser.py
@@ -527,11 +527,14 @@ class DoxygenParser():
             pass
 
         doxy_deprecated = False
+        has_description = True
         try:
             for p in member_elem.find('detaileddescription').getiterator('para'):
                 for s in p.getiterator('xrefsect'):
                     if s.find('xreftitle') is not None and 'Deprecated' in s.find('xreftitle').text:
                         doxy_deprecated = True
+                        if s.find('xrefdescription') is None or s.find('xrefdescription').find('para') is None:
+                            has_description = False
                         break
         except:
             assert 0, member_elem.find('definition').text
@@ -539,6 +542,10 @@ class DoxygenParser():
         if not decl_deprecated and not doxy_deprecated:
             return False
 
+        if doxy_deprecated and not has_description:
+            assert has_description, 'Error: Missing description for deprecated method {}'.format(
+                member_elem.find('definition').text)
+
         # only functions for now, but in future this should also apply for enums and variables
         if member_elem.get('kind') in ('function', 'variable'):
             assert decl_deprecated, 'Error: Missing Q_DECL_DEPRECATED for {}'.format(member_elem.find('definition').text)