Improve API, docs for QgsDistanceArea

nyalldawson · nyalldawson · commit b6c714ac20ea · 2016-02-03T18:57:10.000+11:00
diff --git a/python/core/qgsdistancearea.sip b/python/core/qgsdistancearea.sip
@@ -15,12 +15,28 @@ class QgsDistanceArea
     //! Copy constructor
     QgsDistanceArea( const QgsDistanceArea &origDA );
 
-    //! sets whether coordinates must be projected to ellipsoid before measuring
+    /** Sets whether coordinates must be projected to ellipsoid before measuring
+     * @note for calculations to use the ellipsoid, both the ellipsoid mode must be true
+     * and an ellipse must be set
+     * @see setEllipsoid()
+     * @see willUseEllipsoid()
+     */
     void setEllipsoidalMode( bool flag );
 
-    //! returns projections enabled flag
+    /** Returns whether ellipsoidal calculations are enabled
+     * @see willUseEllipsoid()
+     * @see setEllipsoidalMode()
+     */
     bool ellipsoidalEnabled() const;
 
+    /** Returns whether calculations will use the ellipsoid. Calculations will only use the
+     * ellipsoid if ellipsoidalEnabled() is true and an ellipsoid has been set.
+     * @note added in QGIS 2.14
+     * @see ellipsoidalEnabled()
+     * @see ellipsoid()
+     */
+    bool willUseEllipsoid() const;
+
     //! sets source spatial reference system (by QGIS CRS)
     void setSourceCrs( long srsid );
 
@@ -38,14 +54,31 @@ class QgsDistanceArea
     //! What sort of coordinate system is being used?
     bool geographic() const;
 
-    //! sets ellipsoid by its acronym
+    /** Sets ellipsoid by its acronym. Calculations will only use the ellipsoid if
+     * both the ellipsoid has been set and ellipsoidalEnabled() is true.
+     * @returns true if ellipsoid was successfully set
+     * @see ellipsoid()
+     * @see setEllipsoidalMode()
+     * @see willUseEllipsoid()
+     */
     bool setEllipsoid( const QString& ellipsoid );
 
-    //! Sets ellipsoid by supplied radii
+    /** Sets ellipsoid by supplied radii. Calculations will only use the ellipsoid if
+     * both the ellipsoid has been set and ellipsoidalEnabled() is true.
+     * @returns true if ellipsoid was successfully set
+     * @see ellipsoid()
+     * @see setEllipsoidalMode()
+     * @see willUseEllipsoid()
+     */
     // Inverse flattening is calculated with invf = a/(a-b)
     bool setEllipsoid( double semiMajor, double semiMinor );
 
-    //! returns ellipsoid's acronym
+    /** Returns ellipsoid's acronym. Calculations will only use the
+     * ellipsoid if ellipsoidalEnabled() is true and an ellipsoid has been set.
+     * @see setEllipsoid()
+     * @see ellipsoidalEnabled()
+     * @see willUseEllipsoid()
+     */
     QString ellipsoid() const;
 
     //! returns ellipsoid's semi major axis
diff --git a/src/core/qgsdistancearea.cpp b/src/core/qgsdistancearea.cpp
@@ -98,6 +98,11 @@ void QgsDistanceArea::setEllipsoidalMode( bool flag )
   mEllipsoidalMode = flag;
 }
 
+bool QgsDistanceArea::willUseEllipsoid() const
+{
+  return mEllipsoidalMode && mEllipsoid != GEO_NONE;
+}
+
 void QgsDistanceArea::setSourceCrs( long srsid )
 {
   QgsCoordinateReferenceSystem srcCRS;
diff --git a/src/core/qgsdistancearea.h b/src/core/qgsdistancearea.h
@@ -48,12 +48,28 @@ class CORE_EXPORT QgsDistanceArea
     //! Assignment operator
     QgsDistanceArea & operator=( const QgsDistanceArea & origDA );
 
-    //! sets whether coordinates must be projected to ellipsoid before measuring
+    /** Sets whether coordinates must be projected to ellipsoid before measuring
+     * @note for calculations to use the ellipsoid, both the ellipsoid mode must be true
+     * and an ellipse must be set
+     * @see setEllipsoid()
+     * @see willUseEllipsoid()
+     */
     void setEllipsoidalMode( bool flag );
 
-    //! returns projections enabled flag
+    /** Returns whether ellipsoidal calculations are enabled
+     * @see willUseEllipsoid()
+     * @see setEllipsoidalMode()
+     */
     bool ellipsoidalEnabled() const { return mEllipsoidalMode; }
 
+    /** Returns whether calculations will use the ellipsoid. Calculations will only use the
+     * ellipsoid if ellipsoidalEnabled() is true and an ellipsoid has been set.
+     * @note added in QGIS 2.14
+     * @see ellipsoidalEnabled()
+     * @see ellipsoid()
+     */
+    bool willUseEllipsoid() const;
+
     //! sets source spatial reference system (by QGIS CRS)
     void setSourceCrs( long srsid );
 
@@ -71,14 +87,31 @@ class CORE_EXPORT QgsDistanceArea
     //! What sort of coordinate system is being used?
     bool geographic() const { return mCoordTransform->sourceCrs().geographicFlag(); }
 
-    //! sets ellipsoid by its acronym
+    /** Sets ellipsoid by its acronym. Calculations will only use the ellipsoid if
+     * both the ellipsoid has been set and ellipsoidalEnabled() is true.
+     * @returns true if ellipsoid was successfully set
+     * @see ellipsoid()
+     * @see setEllipsoidalMode()
+     * @see willUseEllipsoid()
+     */
     bool setEllipsoid( const QString& ellipsoid );
 
-    //! Sets ellipsoid by supplied radii
+    /** Sets ellipsoid by supplied radii. Calculations will only use the ellipsoid if
+     * both the ellipsoid has been set and ellipsoidalEnabled() is true.
+     * @returns true if ellipsoid was successfully set
+     * @see ellipsoid()
+     * @see setEllipsoidalMode()
+     * @see willUseEllipsoid()
+     */
     // Inverse flattening is calculated with invf = a/(a-b)
     bool setEllipsoid( double semiMajor, double semiMinor );
 
-    //! returns ellipsoid's acronym
+    /** Returns ellipsoid's acronym. Calculations will only use the
+     * ellipsoid if ellipsoidalEnabled() is true and an ellipsoid has been set.
+     * @see setEllipsoid()
+     * @see ellipsoidalEnabled()
+     * @see willUseEllipsoid()
+     */
     QString ellipsoid() const { return mEllipsoid; }
 
     //! returns ellipsoid's semi major axis
diff --git a/tests/src/python/test_qgsdistancearea.py b/tests/src/python/test_qgsdistancearea.py
@@ -121,5 +121,23 @@ def testMeasureMultiPolygon(self):
         perimeter = da.measurePerimeter(polygon)
         assert perimeter == 16, "Expected:\n%f\nGot:\n%f\n" % (16, perimeter)
 
+    def testWillUseEllipsoid(self):
+        """test QgsDistanceArea::willUseEllipsoid """
+
+        da = QgsDistanceArea()
+        da.setEllipsoidalMode(False)
+        da.setEllipsoid("NONE")
+        self.assertFalse(da.willUseEllipsoid())
+
+        da.setEllipsoidalMode(True)
+        self.assertFalse(da.willUseEllipsoid())
+
+        da.setEllipsoid("WGS84")
+        assert da.willUseEllipsoid()
+
+        da.setEllipsoidalMode(False)
+        self.assertFalse(da.willUseEllipsoid())
+
+
 if __name__ == '__main__':
     unittest.main()

Original file line number	Diff line number	Diff line change
`@@ -98,6 +98,11 @@ void QgsDistanceArea::setEllipsoidalMode( bool flag )`
`98`	`98`	`mEllipsoidalMode = flag;`
`99`	`99`	`}`
`100`	`100`
	`101`	`+bool QgsDistanceArea::willUseEllipsoid() const`
	`102`	`+{`
	`103`	`+ return mEllipsoidalMode && mEllipsoid != GEO_NONE;`
	`104`	`+}`
	`105`	`+`
`101`	`106`	`void QgsDistanceArea::setSourceCrs( long srsid )`
`102`	`107`	`{`
`103`	`108`	`QgsCoordinateReferenceSystem srcCRS;`