Add unit test to prevent deprecated methods without description

nyalldawson · nyalldawson · commit 5e360f90e87d · 2018-05-25T16:31:03.000+10:00
And add missing descriptions
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -527,18 +527,25 @@ def isDeprecated(self, member_elem):
             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
 
         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)

Original file line number	Diff line number	Diff line change
`@@ -158,7 +158,7 @@ class CORE_EXPORT QgsProject : public QObject, public QgsExpressionContextGenera`
`158`	`158`	`*`
`159`	`159`	`* \see fileName()`
`160`	`160`	`* \since QGIS 2.9`
`161`		`- * \deprecated`
	`161`	`+ * \deprecated Use absoluteFilePath(), baseName() or lastModifiedTime() instead`
`162`	`162`	`*/`
`163`	`163`	`Q_DECL_DEPRECATED QFileInfo fileInfo() const SIP_DEPRECATED;`
`164`	`164`