Add extra check for deprecations to documentation test

This check tests that if a function has been declared deprecated
with either Q_DECL_DEPRECATED or has a @deprecated Doxygen note
then it MUST have both the Q_DECL_DEPRECATD and @deprecated note.

It's important that both are used, as Q_DECL_DEPRECATED allows
throwing a warning if that method is used in code, while the
@deprecated doxygen note gives an indication to devs/PyQGIS users
of why it's deprecated and what should be used instead.

Ideally we'd also test for SIP /Deprecated/ tags, but I can't
find any reliable way to do this.

python/core/composer/qgsatlascomposition.sip

@@ -254,10 +254,14 @@ public:
      */
     void setMargin( float margin ) /Deprecated/;
 
+    //! @deprecated use sortKeyAttributeName instead
     int sortKeyAttributeIndex() const /Deprecated/;
+    //! @deprecated use setSortKeyAttributeName instead
     void setSortKeyAttributeIndex( int idx ) /Deprecated/;
 
-    /** Returns the current atlas feature. Must be called after prepareForFeature(). */
+    /** Returns the current atlas feature. Must be called after prepareForFeature( i ).
+     * @deprecated use feature() instead
+    */
     QgsFeature* currentFeature() /Deprecated/;
 
     /** Returns the current atlas geometry in the given projection system (default to the coverage layer's CRS) */

python/core/composer/qgscomposeritem.sip

@@ -688,7 +688,9 @@ class QgsComposerItem : QgsComposerObject, QGraphicsRectItem
      */
     void drawArrowHead( QPainter* p, double x, double y, double angle, double arrowHeadWidth ) const /Deprecated/;
 
-    /** Returns angle of the line from p1 to p2 (clockwise, starting at N)*/
+    /** Returns angle of the line from p1 to p2 (clockwise, starting at N)
+     * @deprecated will be removed in QGIS 3.0
+    */
     double angle( const QPointF& p1, const QPointF& p2 ) const /Deprecated/;
 
     /** Returns the current (zoom level dependent) tolerance to decide if mouse position is close enough to the

python/core/composer/qgscomposerlegend.sip

@@ -47,7 +47,7 @@ class QgsComposerLegend : QgsComposerItem
     void adjustBoxSize();
 
     /** Returns pointer to the legend model*/
-    //! @note deprecated in 2.6 - use modelV2()
+    //! @deprecated in 2.6 - use modelV2()
     QgsLegendModel* model() /Deprecated/;
 
     //! @note added in 2.6

python/core/composer/qgscomposermap.sip

@@ -740,6 +740,7 @@ class QgsComposerMap : QgsComposerItem
     /** Transforms map coordinates to item coordinates (considering rotation and move offset)*/
     QPointF mapToItemCoords( const QPointF& mapCoords ) const;
 
+    //! @deprecated will be removed in QGIS 3.0
     void connectMapOverviewSignals() /Deprecated/;
 
     /** Calculates the extent to request and the yShift of the top-left point in case of rotation.

python/core/composer/qgscomposertablev2.sip

@@ -509,6 +509,7 @@ class QgsComposerTableV2: QgsComposerMultiFrame
     /** Calculates how many content rows are visible within a given frame
      * @param frameIndex index number for frame
      * @returns number of visible content rows (excludes header rows)
+     * @deprecated will be removed in QGIS 3.0
      */
     int rowsVisible( const int frameIndex ) const /Deprecated/;
 
@@ -517,6 +518,7 @@ class QgsComposerTableV2: QgsComposerMultiFrame
      * @param frameHeight height of frame
      * @param includeHeader set to true if frame would include a header row
      * @returns number of visible content rows (excluding header row)
+     * @deprecated will be removed in QGIS 3.0
      */
     int rowsVisible( const double frameHeight, const bool includeHeader ) const /Deprecated/;
 
@@ -525,6 +527,7 @@ class QgsComposerTableV2: QgsComposerMultiFrame
      * @param extent visible extent
      * @param frameIndex index number for frame
      * @returns row range
+     * @deprecated will be removed in QGIS 3.0
      */
     QPair<int, int> rowRange( const QRectF &extent, const int frameIndex ) const /Deprecated/;
 
@@ -533,6 +536,7 @@ class QgsComposerTableV2: QgsComposerMultiFrame
      * @param rows number of rows shown in table
      * @param drawHeaderLines set to true to include for the table header
      * @see drawVerticalGridLines
+     * @deprecated will be removed in QGIS 3.0
      */
     void drawHorizontalGridLines( QPainter* painter, const int rows, const bool drawHeaderLines ) const /Deprecated/;
 
@@ -547,6 +551,7 @@ class QgsComposerTableV2: QgsComposerMultiFrame
      * @see drawVerticalGridLines
      * @see calculateMaxColumnWidths
      * @note not available in python bindings
+     * @deprecated will be removed in QGIS 3.0
      */
    // void drawVerticalGridLines( QPainter* painter, const QMap<int, double>& maxWidthMap, const int numberRows, const bool hasHeader, const bool mergeCells = false ) const /Deprecated/;
 

python/core/composer/qgscomposition.sip

@@ -355,6 +355,7 @@ class QgsComposition : QGraphicsScene
       composer user interface item properties).
       @param item the item.
       @return QgsComposerHtml pointer or 0 pointer if no such item exists.
+      @deprecated Use QgsComposerFrame::multiFrame() instead
      */
     const QgsComposerHtml* getComposerHtmlByItem( QgsComposerItem *item ) const /Deprecated/;
 

python/core/diagram/qgsdiagram.sip

@@ -10,6 +10,8 @@ class QgsDiagram
     virtual QgsDiagram* clone() const = 0 /Factory/;
 
     void clearCache();
+
+    //! @deprecated use QgsExpressionContext variant instead
     QgsExpression* getExpression( const QString& expression, const QgsFields* fields ) /Deprecated/;
 
     /** Returns a prepared expression for the specified context.

python/core/qgscachedfeatureiterator.sip

@@ -15,7 +15,7 @@ class QgsCachedFeatureIterator : QgsAbstractFeatureIterator
      * @deprecated Use QgsCachedFeatureIterator( QgsVectorLayerCache* vlCache, QgsFeatureRequest featureRequest )
      *             instead
      */
-    QgsCachedFeatureIterator( QgsVectorLayerCache* vlCache, const QgsFeatureRequest& featureRequest, const QgsFeatureIds& featureIds );
+    QgsCachedFeatureIterator( QgsVectorLayerCache* vlCache, const QgsFeatureRequest& featureRequest, const QgsFeatureIds& featureIds ) /Deprecated/;
 
     /**
      * This constructor creates a feature iterator, that delivers all cached features. No request is made to the backend.

python/core/qgsdatadefined.sip

@@ -119,13 +119,15 @@ class QgsDataDefined
     /** Prepares the expression using a vector layer
      * @param layer vector layer
      * @returns true if expression was successfully prepared
+     * @deprecated use QgsExpressionContext variant instead
      */
     bool prepareExpression( QgsVectorLayer* layer ) /Deprecated/;
 
     /** Prepares the expression using a fields collection
      * @param fields
      * @returns true if expression was successfully prepared
      * @note added in QGIS 2.9
+     * @deprecated use QgsExpressionContext variant instead
      */
     bool prepareExpression( const QgsFields &fields ) /Deprecated/;
 
@@ -145,12 +147,14 @@ class QgsDataDefined
 
     /** Returns the columns referenced by the QgsDataDefined
      * @param layer vector layer, used for preparing the expression if required
+     * @deprecated use QgsExpressionContext variant instead
      */
     QStringList referencedColumns( QgsVectorLayer* layer ) /Deprecated/;
 
     /** Returns the columns referenced by the QgsDataDefined
      * @param fields vector layer, used for preparing the expression if required
      * @note added in QGIS 2.9
+     * @deprecated use QgsExpressionContext variant instead
      */
     QStringList referencedColumns( const QgsFields& fields ) /Deprecated/;
 

python/core/qgsdataitem.sip

@@ -89,7 +89,7 @@ class QgsDataItem : QObject
     virtual void setState( State state );
 
     //! @deprecated in 2.8, use state()
-    bool isPopulated();
+    bool isPopulated() /Deprecated/;
 
     // Insert new child using alphabetical order based on mName, emits necessary signal to model before and after, sets parent and connects signals
     // refresh - refresh populated item, emit signals to model

python/core/qgsexpression.sip

@@ -17,6 +17,7 @@ class QgsExpression
     const QgsExpression::Node* rootNode() const;
 
     //! Get the expression ready for evaluation - find out column indexes.
+    //! @deprecated use prepare( const QgsExpressionContext *context ) instead
     bool prepare( const QgsFields &fields ) /Deprecated/;
 
     /** Get the expression ready for evaluation - find out column indexes.
@@ -40,20 +41,24 @@ class QgsExpression
 
     //! Evaluate the feature and return the result
     //! @note prepare() should be called before calling this method
+    //! @deprecated use evaluate( const QgsExpressionContext* context ) instead
     QVariant evaluate( const QgsFeature* f ) /Deprecated/;
 
     //! Evaluate the feature and return the result
     //! @note prepare() should be called before calling this method
     //! @note available in python bindings as evaluatePrepared
+    //! @deprecated use evaluate( const QgsExpressionContext* context ) instead
     QVariant evaluate( const QgsFeature& f ) /PyName=evaluatePrepared,Deprecated/;
 
     //! Evaluate the feature and return the result
     //! @note this method does not expect that prepare() has been called on this instance
+    //! @deprecated use evaluate( const QgsExpressionContext* context ) instead
     QVariant evaluate( const QgsFeature* f, const QgsFields& fields ) /Deprecated/;
 
     //! Evaluate the feature and return the result
     //! @note this method does not expect that prepare() has been called on this instance
     //! @note not available in python bindings
+    //! @deprecated use evaluate( const QgsExpressionContext* context ) instead
     // inline QVariant evaluate( const QgsFeature& f, const QgsFields& fields ) { return evaluate( &f, fields ); }
 
     /** Evaluate the feature and return the result.
@@ -77,8 +82,10 @@ class QgsExpression
     void setEvalErrorString( const QString& str );
 
     //! Set the number for $rownum special column
+    //! @deprecated use QgsExpressionContext to set row number instead
     void setCurrentRowNumber( int rowNumber ) /Deprecated/;
     //! Return the number used for $rownum special column
+    //! @deprecated use QgsExpressionContext to retrieve row number instead
     int currentRowNumber() /Deprecated/;
 
     /** Assign a special column
@@ -102,6 +109,7 @@ class QgsExpression
      */
     bool isField() const;
 
+    //! @deprecated use QgsExpressionContext variant instead
     static bool isValid( const QString& text, const QgsFields& fields, QString &errorMessage ) /Deprecated/;
 
     /** Tests whether a string is a valid expression.
@@ -143,6 +151,7 @@ class QgsExpression
        @param substitutionMap
        @param distanceArea optional QgsDistanceArea. If specified, the QgsDistanceArea is used for distance
        and area conversion
+       @deprecated use QgsExpressionContext variant instead
     */
     static QString replaceExpressionText( const QString &action, const QgsFeature *feat,
                                           QgsVectorLayer *layer,
@@ -289,6 +298,7 @@ class QgsExpression
         /** The help text for the function. */
         const QString helptext();
 
+        //! @deprecated Use QgsExpressionContext variant instead
         virtual QVariant func( const QVariantList& values, const QgsFeature* f, QgsExpression* parent ) /Deprecated/;
 
         /** Returns result of evaluating the function.
@@ -405,6 +415,7 @@ class QgsExpression
         virtual QgsExpression::NodeType nodeType() const = 0;
         // abstract virtual eval function
         // errors are reported to the parent
+        //! @deprecated Use QgsExpressionContext variant instead
         virtual QVariant eval( QgsExpression* parent, const QgsFeature* f ) /Deprecated/;
 
         /** Evaluation function for nodes. Errors are reported to the parent.
@@ -414,6 +425,7 @@ class QgsExpression
 
         // abstract virtual preparation function
         // errors are reported to the parent
+        //! @deprecated Use QgsExpressionContext variant instead
         virtual bool prepare( QgsExpression* parent, const QgsFields &fields ) /Deprecated/;
 
         /** Preparation function for nodes. Errors are reported to the parent.

python/core/qgsfeature.sip

@@ -356,6 +356,7 @@ class QgsFeature
      * @returns pointer to feature's geometry
      * @see geometry
      * @see setGeometry
+     * @deprecated use constGeometry() instead
      */
     QgsGeometry *geometryAndOwnership() /Factory,Deprecated/;
 
@@ -391,7 +392,7 @@ class QgsFeature
      * @see geometryAndOwnership
      * @deprecated will be removed in QGIS 3.0
      */
-    void setGeometryAndOwnership( unsigned char * geom /Transfer/, size_t length );
+    void setGeometryAndOwnership( unsigned char * geom /Transfer/, size_t length ) /Deprecated/;
 
     /** Assign a field map with the feature to allow attribute access by attribute name.
      *  @param fields The attribute fields which this feature holds

python/core/qgsowsconnection.sip

@@ -26,5 +26,6 @@ class QgsOWSConnection : QObject
     QgsDataSourceURI uri();
     QString mConnectionInfo;
 
+    //! @deprecated use mConnectionInfo instead
     QString connectionInfo() /Deprecated/;
 };

python/core/qgssnapper.sip

@@ -69,7 +69,7 @@ class QgsSnapper
       QgsTolerance::UnitType mUnitType;
     };
 
-    //!@ deprecated since 2.4 - use constructor with QgsMapSettings
+    //!@deprecated since 2.4 - use constructor with QgsMapSettings
     QgsSnapper( QgsMapRenderer *mapRender ) /Deprecated/;
 
     explicit QgsSnapper( const QgsMapSettings& mapSettings );

python/core/qgsvectorlayer.sip

@@ -324,8 +324,10 @@ class QgsVectorLayer : QgsMapLayer
 
     struct RangeData
     {
-      RangeData();
-      RangeData( const QVariant& theMin, const QVariant& theMax, const QVariant& theStep );
+      //! @deprecated Use the editorWidgetV2() system instead
+      RangeData() /Deprecated/;
+      //! @deprecated Use the editorWidgetV2() system instead
+      RangeData( const QVariant& theMin, const QVariant& theMax, const QVariant& theStep ) /Deprecated/;
 
       QVariant mMin;
       QVariant mMax;
@@ -678,7 +680,7 @@ class QgsVectorLayer : QgsMapLayer
      *
      * @deprecated Will be removed for QGIS 3 in favor of importNamedStyle
      */
-    virtual bool applyNamedStyle( const QString& namedStyle, QString &errorMsg /Out/ );
+    virtual bool applyNamedStyle( const QString& namedStyle, QString &errorMsg /Out/ ) /Deprecated/;
 
     /** Convert a saved attribute editor element into a AttributeEditor structure as it's used internally.
      * @param elem the DOM element
@@ -946,7 +948,7 @@ class QgsVectorLayer : QgsMapLayer
     bool draw( QgsRenderContext& rendererContext );
 
     /** Draws the layer labels using the old labeling engine
-     * @note deprecated
+     * @deprecated will be removed in QGIS 3.0
     */
     void drawLabels( QgsRenderContext& rendererContext ) /Deprecated/;
 

python/core/raster/qgsrasterlayer.sip

@@ -169,7 +169,9 @@ class QgsRasterLayer : QgsMapLayer
     /** \brief Set default contrast enhancement */
     void setDefaultContrastEnhancement();
 
-    /** \brief Overloaded version of the above function for convenience when restoring from xml */
+    /** \brief Overloaded version of the above function for convenience when restoring from xml
+     * @deprecated Deprecated since QGIS 2.10. Use setRendererForDrawingStyle() or directly setRenderer()
+     */
     void setDrawingStyle( const QString & theDrawingStyleQString ) /Deprecated/;
 
     /** \brief [ data provider interface ] A wrapper function to emit a progress update signal */
@@ -179,7 +181,7 @@ class QgsRasterLayer : QgsMapLayer
     virtual QStringList subLayers() const;
 
     /** \brief Draws a preview of the rasterlayer into a pixmap
-    @note - use previewAsImage() for rendering with QGIS>=2.4 */
+    @deprecated use previewAsImage() for rendering with QGIS>=2.4 */
     QPixmap previewAsPixmap( const QSize& size, const QColor& bgColor = QColor( 255, 255, 255 ) ) /Deprecated/;
 
     /** \brief Draws a preview of the rasterlayer into a QImage

python/core/symbology-ng/qgsrendererv2.sip

@@ -64,6 +64,7 @@ class QgsFeatureRendererV2
     /** To be overridden
      * @param feature feature
      * @return returns pointer to symbol or 0 if symbol was not found
+     * @deprecated use symbolForFeature( QgsFeature& feature, QgsRenderContext& context ) instead
      */
     virtual QgsSymbolV2* symbolForFeature( QgsFeature& feature ) /Deprecated/;
 
@@ -83,6 +84,7 @@ class QgsFeatureRendererV2
      * symbol which can be used as an identifier for renderer's rule - the former may return a temporary replacement
      * of a symbol for use in rendering.
      * @note added in 2.6
+     * @deprecated use originalSymbolForFeature( QgsFeature& feature, QgsRenderContext& context ) instead
      */
     virtual QgsSymbolV2* originalSymbolForFeature( QgsFeature& feature ) /Deprecated/;
 
@@ -139,7 +141,9 @@ class QgsFeatureRendererV2
     //! returns bitwise OR-ed capabilities of the renderer
     virtual int capabilities();
 
-    //! for symbol levels
+    /** For symbol levels
+     * @deprecated use symbols( QgsRenderContext& context ) instead
+     */
     virtual QgsSymbolV2List symbols() /Deprecated/;
 
     /** Returns list of symbols used by the renderer.
@@ -217,9 +221,11 @@ class QgsFeatureRendererV2
     //! sets rotation field of renderer (if supported by the renderer)
     virtual void setRotationField( const QString& fieldName ) /Deprecated/;
 
-    //! return whether the renderer will render a feature or not.
-    //! Must be called between startRender() and stopRender() calls.
-    //! Default implementation uses symbolForFeature().
+    /** Returns whether the renderer will render a feature or not.
+     * Must be called between startRender() and stopRender() calls.
+     * Default implementation uses symbolForFeature().
+     * @deprecated use willRenderFeature( QgsFeature& feat, QgsRenderContext& context ) instead
+     */
     virtual bool willRenderFeature( QgsFeature& feat ) /Deprecated/;
 
     /** Returns whether the renderer will render a feature or not.
@@ -231,9 +237,11 @@ class QgsFeatureRendererV2
     //TODO - QGIS 3.0 change PyName to willRenderFeature when deprecated method is removed
     virtual bool willRenderFeature( QgsFeature& feat, QgsRenderContext& context ) /PyName=willRenderFeature2/;
 
-    //! return list of symbols used for rendering the feature.
-    //! For renderers that do not support MoreSymbolsPerFeature it is more efficient
-    //! to use symbolForFeature()
+    /** Returns list of symbols used for rendering the feature.
+     * For renderers that do not support MoreSymbolsPerFeature it is more efficient
+     * to use symbolForFeature()
+     * @deprecated use symbolsForFeature( QgsFeature& feat, QgsRenderContext& context ) instead
+     */
     virtual QgsSymbolV2List symbolsForFeature( QgsFeature& feat ) /Deprecated/;
 
     /** Returns list of symbols used for rendering the feature.
@@ -245,9 +253,11 @@ class QgsFeatureRendererV2
     //TODO - QGIS 3.0 change PyName to symbolsForFeature when deprecated method is removed
     virtual QgsSymbolV2List symbolsForFeature( QgsFeature& feat, QgsRenderContext& context ) /PyName=symbolsForFeature2/;
 
-    //! Equivalent of originalSymbolsForFeature() call
-    //! extended to support renderers that may use more symbols per feature - similar to symbolsForFeature()
-    //! @note added in 2.6
+    /** Equivalent of originalSymbolsForFeature() call
+     * extended to support renderers that may use more symbols per feature - similar to symbolsForFeature()
+     * @note added in 2.6
+     * @deprecated use originalSymbolsForFeature( QgsFeature& feat, QgsRenderContext& context ) instead
+     */
     virtual QgsSymbolV2List originalSymbolsForFeature( QgsFeature& feat ) /Deprecated/;
 
      /** Equivalent of originalSymbolsForFeature() call