[doxygen] fix badly placed \returns

qgis · Dec 16, 2017 · 281392b · 281392b
1 parent e6f657c
commit 281392b
Show file tree

Hide file tree

Showing 21 changed files with 57 additions and 60 deletions.
diff --git a/src/core/auth/qgsauthmanager.h b/src/core/auth/qgsauthmanager.h
@@ -469,8 +469,8 @@ class CORE_EXPORT QgsAuthManager : public QObject
 
     /**
      * \brief ignoredSslErrorCache Get ignored SSL error cache, keyed with cert/connection's sha:host:port.
-     * \note not available in Python bindings
      * \return hash keyed with cert/connection's sha:host:port.
+     * \note not available in Python bindings
      * \since QGIS 3.0
      */
     QHash<QString, QSet<QSslError::SslError> > ignoredSslErrorCache() { return mIgnoredSslErrorsCache; } SIP_SKIP

diff --git a/src/core/geometry/qgsgeometry.h b/src/core/geometry/qgsgeometry.h
@@ -1137,8 +1137,8 @@ class CORE_EXPORT QgsGeometry
 
     /**
      * Exports the geometry to WKT
-     * \note precision parameter added in QGIS 2.4
      * \returns true in case of success and false else
+     * \note precision parameter added in QGIS 2.4
      */
     QString asWkt( int precision = 17 ) const;
 

diff --git a/src/core/geometry/qgsgeometryutils.h b/src/core/geometry/qgsgeometryutils.h
@@ -70,8 +70,8 @@ class CORE_EXPORT QgsGeometryUtils
      * \param distance distance to traverse along geometry
      * \param previousVertex will be set to previous vertex ID
      * \param nextVertex will be set to next vertex ID
-     * \note if the distance coincides exactly with a vertex, then both previousVertex and nextVertex will be set to this vertex
      * \returns true if vertices were successfully retrieved
+     * \note if the distance coincides exactly with a vertex, then both previousVertex and nextVertex will be set to this vertex
      * \since QGIS 3.0
      */
     static bool verticesAtDistance( const QgsAbstractGeometry &geometry,

diff --git a/src/core/geometry/qgsgeos.h b/src/core/geometry/qgsgeos.h
@@ -265,8 +265,8 @@ class CORE_EXPORT QgsGeos: public QgsGeometryEngine
      * where this linestring comes to the specified point.
      * \param point point to seek proximity to
      * \param errorMsg error messages emitted, if any
-     * \note only valid for linestring geometries
      * \returns distance along line, or -1 on error
+     * \note only valid for linestring geometries
      */
     double lineLocatePoint( const QgsPoint &point, QString *errorMsg = nullptr ) const;
 

diff --git a/src/core/qgsapplication.h b/src/core/qgsapplication.h
@@ -205,8 +205,8 @@ class CORE_EXPORT QgsApplication : public QApplication
     /**
      * \brief All themes found in ~/.qgis3/themes folder.
      * The path is to the root folder for the theme
-     * \note Valid theme folders must contain a style.qss file.
      * \returns A hash of theme name and theme path. Valid theme folders contain style.qss
+     * \note Valid theme folders must contain a style.qss file.
      */
     static QHash<QString, QString> uiThemes();
 

diff --git a/src/core/qgscoordinatereferencesystem.h b/src/core/qgscoordinatereferencesystem.h
@@ -304,9 +304,9 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
 
     /**
      * Sets this CRS by lookup of the given ID in the CRS database.
+     * \returns True on success else false
      * \note We encourage you to use EPSG code, WKT or Proj4 to describe CRS's in your code
      * wherever possible. Internal QGIS CRS IDs are not guaranteed to be permanent / involatile.
-     * \returns True on success else false
      */     // TODO QGIS 3: remove type and always use EPSG code, rename to createFromEpsg
     bool createFromId( const long id, CrsType type = PostgisCrsId );
 
@@ -316,8 +316,8 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
      * Accepts both "<auth>:<code>" format and OGC URN "urn:ogc:def:crs:<auth>:[<version>]:<code>".
      * It also recognizes "QGIS", "USER", "CUSTOM" authorities, which all have the same meaning
      * and refer to QGIS internal CRS IDs.
-     * \note this method uses an internal cache. Call invalidateCache() to clear the cache.
      * \returns True on success else false
+     * \note this method uses an internal cache. Call invalidateCache() to clear the cache.
      * \see fromOgcWmsCrs()
      */     // TODO QGIS 3: remove "QGIS" and "CUSTOM", only support "USER" (also returned by authid())
     bool createFromOgcWmsCrs( const QString &crs );
@@ -336,10 +336,10 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
      * and createFromOgcWmsCrs() is used to initialize the object.
      * Otherwise the WKT will be converted to a proj4 string and createFromProj4()
      * set up the object.
-     * \note Some members may be left blank if no match can be found in CRS database.
-     * \note this method uses an internal cache. Call invalidateCache() to clear the cache.
      * \param wkt The WKT for the desired spatial reference system.
      * \returns True on success else false
+     * \note Some members may be left blank if no match can be found in CRS database.
+     * \note this method uses an internal cache. Call invalidateCache() to clear the cache.
      * \see fromWkt()
      */
     bool createFromWkt( const QString &wkt );
@@ -349,9 +349,9 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
      *
      * If the srsid is < USER_CRS_START_ID, system CRS database is used, otherwise
      * user's local CRS database from home directory is used.
-     * \note this method uses an internal cache. Call invalidateCache() to clear the cache.
      * \param srsId The internal QGIS CRS ID for the desired spatial reference system.
      * \returns True on success else false
+     * \note this method uses an internal cache. Call invalidateCache() to clear the cache.
      * \see fromSrsId()
      */
     bool createFromSrsId( const long srsId );
@@ -373,10 +373,10 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
      *   a match where the parameters are in a different order
      * - if none of the above match, use findMatchingProj()
      *
-     * \note Some members may be left blank if no match can be found in CRS database.
-     * \note this method uses an internal cache. Call invalidateCache() to clear the cache.
      * \param projString A proj4 format string
      * \returns True on success else false
+     * \note Some members may be left blank if no match can be found in CRS database.
+     * \note this method uses an internal cache. Call invalidateCache() to clear the cache.
      * \see fromProj4()
      */
     bool createFromProj4( const QString &projString );
@@ -407,10 +407,10 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
      *
      * For more details on supported formats see OGRSpatialReference::SetFromUserInput()
      * ( http://www.gdal.org/ogr/classOGRSpatialReference.html#aec3c6a49533fe457ddc763d699ff8796 )
-     * \note this function generates a WKT string using OSRSetFromUserInput() and
-     * passes it to createFromWkt() function.
      * \param definition A String containing a coordinate reference system definition.
      * \returns True on success else false
+     * \note this function generates a WKT string using OSRSetFromUserInput() and
+     * passes it to createFromWkt() function.
      */    // TODO QGIS3: rename to createFromStringOGR so it is clear it's similar to createFromString, just different backend
     bool createFromUserInput( const QString &definition );
 
@@ -721,10 +721,10 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
 
     /**
      * Get a record from the srs.db or qgis.db backends, given an sql statement.
-     * \note only handles queries that return a single record.
-     * \note it will first try the system srs.db then the users qgis.db!
      * \param sql The sql query to execute
      * \returns An associative array of field name <-> value pairs
+     * \note only handles queries that return a single record.
+     * \note it will first try the system srs.db then the users qgis.db!
      */
     RecordMap getRecord( const QString &sql );
 

diff --git a/src/core/qgsdistancearea.h b/src/core/qgsdistancearea.h
@@ -183,23 +183,22 @@ class CORE_EXPORT QgsDistanceArea
      * Calculates the distance from one point with distance in meters and azimuth (direction)
      * When the sourceCrs() is geographic, computeSpheroidProject() will be called
      * otherwise QgsPoint.project() will be called after QgsUnitTypes::fromUnitToUnitFactor() has been applied to the distance
-     * \note:
-     *  The input Point must be in the coordinate reference system being used
-     * \since QGIS 3.0
      * \param p1 start point [can be Cartesian or Geographic]
      * \param distance must be in meters
      * \param azimuth - azimuth in radians, clockwise from North
      * \param projectedPoint calculated projected point
      * \return distance in mapUnits
      * \see sourceCrs()
      * \see computeSpheroidProject()
+     * \note The input Point must be in the coordinate reference system being used
+     * \since QGIS 3.0
      */
     double measureLineProjected( const QgsPointXY &p1, double distance = 1, double azimuth = M_PI_2, QgsPointXY *projectedPoint SIP_OUT = nullptr ) const;
 
     /**
      * Returns the units of distance for length calculations made by this object.
-     * \since QGIS 2.14
      * \see areaUnits()
+     * \since QGIS 2.14
      */
     QgsUnitTypes::DistanceUnit lengthUnits() const;
 
@@ -275,17 +274,17 @@ class CORE_EXPORT QgsDistanceArea
      * location of the projected point. Based on Vincenty's formula
      * for the geodetic direct problem as described in "Geocentric
      * Datum of Australia Technical Manual", Chapter 4.
+     * \param p1 - location of first geographic (latitude/longitude) point as degrees.
+     * \param distance - distance in meters.
+     * \param azimuth - azimuth in radians, clockwise from North
+     * \return p2 - location of projected point as longitude/latitude.
      * \note code (and documentation) taken from rttopo project
      * https://git.osgeo.org/gogs/rttopo/librttopo
      * - spheroid_project.spheroid_project(...)
      * -  Valid bounds checking for degrees (latitude=+- 85.05115) is based values used for
      * -> 'WGS84 Web Mercator (Auxiliary Sphere)' calculations
      * --> latitudes outside these bounds cause the calculations to become unstable and can return invalid results
      * \since QGIS 3.0
-     * \param p1 - location of first geographic (latitude/longitude) point as degrees.
-     * \param distance - distance in meters.
-     * \param azimuth - azimuth in radians, clockwise from North
-     * \return p2 - location of projected point as longitude/latitude.
      */
     QgsPointXY computeSpheroidProject( const QgsPointXY &p1, double distance = 1, double azimuth = M_PI_2 ) const;
 
@@ -295,11 +294,11 @@ class CORE_EXPORT QgsDistanceArea
      * Calculates distance from two points on ellipsoid
      * based on inverse Vincenty's formulae
      *
-     * Points p1 and p2 are expected to be in degrees and in currently used ellipsoid
+     * Points \a p1 and \a p2 are expected to be in degrees and in currently used ellipsoid
      *
+     * \returns distance in meters
      * \note if course1 is not NULL, bearing (in radians) from first point is calculated
      * (the same for course2)
-     * \returns distance in meters
      */
     double computeDistanceBearing( const QgsPointXY &p1, const QgsPointXY &p2,
                                    double *course1 = nullptr, double *course2 = nullptr ) const;

diff --git a/src/core/qgsproject.h b/src/core/qgsproject.h
@@ -235,18 +235,17 @@ class CORE_EXPORT QgsProject : public QObject, public QgsExpressionContextGenera
     /**
      * Writes the project to a file.
      * \param filename destination file
+     * \returns true if project was written successfully
      * \note calling this implicitly sets the project's filename (see setFileName() )
      * \note isDirty() will be set to false if project is successfully written
-     * \returns true if project was written successfully
-     *
      * \since QGIS 3.0
      */
     bool write( const QString &filename );
 
     /**
      * Writes the project to its current associated file (see fileName() ).
-     * \note isDirty() will be set to false if project is successfully written
      * \returns true if project was written successfully
+     * \note isDirty() will be set to false if project is successfully written
      */
     bool write();
 

diff --git a/src/core/qgsuserprofilemanager.h b/src/core/qgsuserprofilemanager.h
@@ -61,11 +61,11 @@ class CORE_EXPORT QgsUserProfileManager : public QObject
      * If no name is given it returns a profile called "default".
      * By default will create the profile folder if not found.
      * By default will init the user settings.
-     * \note Returns a new QgsUserProfile. Ownership transferred to caller.
      * \param defaultProfile The profile name to find. Empty profile name will return "default" for the name.
      * \param createNew Create the profile folder if it doesn't exist.
      * \param initSettings if the settings should be initialized
      * \return The user profile
+     * \note Returns a new QgsUserProfile. Ownership transferred to caller.
      */
     QgsUserProfile *getProfile( const QString &defaultProfile = "default", bool createNew = true, bool initSettings = true ) SIP_FACTORY;
 
@@ -126,8 +126,8 @@ class CORE_EXPORT QgsUserProfileManager : public QObject
      * First checks profile.ini in \\profiles folder
      * Then checks defaultProfile in global settings
      * Finally returns "default" if all else fails
-     * \note Setting overrideLocalProfile in global settings will always ignore profiles.ini
      * \return The name of the default profile.
+     * \note Setting overrideLocalProfile in global settings will always ignore profiles.ini
      */
     QString defaultProfileName() const;
 
@@ -159,9 +159,9 @@ class CORE_EXPORT QgsUserProfileManager : public QObject
 
     /**
      * Deletes a profile from the root profiles folder.
-     * \note There is no undo on this as it deletes the folder from the machine.
      * \param name The name of the profile to delete.
      * \return A QgsError with a message if the profile failed to be deleted.
+     * \note There is no undo on this as it deletes the folder from the machine.
      */
     QgsError deleteProfile( const QString &name );
 

diff --git a/src/core/qgsvectordataprovider.h b/src/core/qgsvectordataprovider.h
@@ -127,8 +127,8 @@ class CORE_EXPORT QgsVectorDataProvider : public QgsDataProvider, public QgsFeat
      * if it is possible that both feature source and provider may need reading/writing to some shared data at the
      * same time, some synchronization mechanisms must be used (e.g. mutexes) to prevent data corruption.
      *
-     * \since QGIS 2.4
      * \returns new instance of QgsAbstractFeatureSource (caller is responsible for deleting it)
+     * \since QGIS 2.4
      */
     virtual QgsAbstractFeatureSource *featureSource() const = 0 SIP_FACTORY;
 

diff --git a/src/core/qgsvectorlayer.h b/src/core/qgsvectorlayer.h
@@ -788,10 +788,10 @@ class CORE_EXPORT QgsVectorLayer : public QgsMapLayer, public QgsExpressionConte
 
     /**
      * Delete a style from the database
-     * \since QGIS 3.0
      * \param styleId the provider's layer_styles table id of the style to delete
      * \param msgError reference to string that will be updated with any error messages
      * \returns true in case of success
+     * \since QGIS 3.0
      */
     virtual bool deleteStyleFromDatabase( const QString &styleId, QString &msgError SIP_OUT );
 
@@ -1151,8 +1151,8 @@ class CORE_EXPORT QgsVectorLayer : public QgsMapLayer, public QgsExpressionConte
     /**
      * Adds topological points for every vertex of the geometry.
      * \param geom the geometry where each vertex is added to segments of other features
-     * \note geom is not going to be modified by the function
      * \returns 0 in case of success
+     * \note geom is not going to be modified by the function
      */
     int addTopologicalPoints( const QgsGeometry &geom );
 

diff --git a/src/core/qgsvectorlayereditutils.h b/src/core/qgsvectorlayereditutils.h
@@ -166,8 +166,8 @@ class CORE_EXPORT QgsVectorLayerEditUtils
     /**
      * Adds topological points for every vertex of the geometry.
      * \param geom the geometry where each vertex is added to segments of other features
+     * \return 0 in case of success
      * \note geom is not going to be modified by the function
-     * \returns 0 in case of success
      */
     int addTopologicalPoints( const QgsGeometry &geom );
 
@@ -177,7 +177,7 @@ class CORE_EXPORT QgsVectorLayerEditUtils
      * no additional vertex is inserted. This method is useful for topological
      * editing.
      * \param p position of the vertex
-     * \returns 0 in case of success
+     * \return 0 in case of success
      */
     int addTopologicalPoints( const QgsPointXY &p );
 

diff --git a/src/core/raster/qgsrasterdataprovider.h b/src/core/raster/qgsrasterdataprovider.h
@@ -303,40 +303,39 @@ class CORE_EXPORT QgsRasterDataProvider : public QgsDataProvider, public QgsRast
     virtual QString htmlMetadata() = 0;
 
     /**
-     * \brief Identify raster value(s) found on the point position. The context
-     *         parameters extent, width and height are important to identify
-     *         on the same zoom level as a displayed map and to do effective
-     *         caching (WCS). If context params are not specified the highest
-     *         resolution is used. capabilities() may be used to test if format
-     *         is supported by provider. Values are set to 'no data' or empty string
-     *         if point is outside data source extent.
+     * Identify raster value(s) found on the point position. The context
+     * parameters extent, width and height are important to identify
+     * on the same zoom level as a displayed map and to do effective
+     * caching (WCS). If context params are not specified the highest
+     * resolution is used. capabilities() may be used to test if format
+     * is supported by provider. Values are set to 'no data' or empty string
+     * if point is outside data source extent.
      *
-     * \note  The arbitraryness of the returned document is enforced by WMS standards
-     *        up to at least v1.3.0
      * \param point coordinates in data source CRS
      * \param format result format
      * \param boundingBox context bounding box
      * \param width context width
      * \param height context height
      * \param dpi context dpi
-     * \returns QgsRaster::IdentifyFormatValue: map of values for each band, keys are band numbers
+     * \return QgsRaster::IdentifyFormatValue: map of values for each band, keys are band numbers
      *         (from 1).
      *         QgsRaster::IdentifyFormatFeature: map of QgsRasterFeatureList for each sublayer
      *         (WMS) - TODO: it is not consistent with QgsRaster::IdentifyFormatValue.
      *         QgsRaster::IdentifyFormatHtml: map of HTML strings for each sublayer (WMS).
      *         Empty if failed or there are no results (TODO: better error reporting).
+     * \note The arbitraryness of the returned document is enforced by WMS standards
+     *       up to at least v1.3.0
      */
     //virtual QMap<int, QVariant> identify( const QgsPointXY & point, QgsRaster::IdentifyFormat format, const QgsRectangle &extent = QgsRectangle(), int width = 0, int height = 0 );
     virtual QgsRasterIdentifyResult identify( const QgsPointXY &point, QgsRaster::IdentifyFormat format, const QgsRectangle &boundingBox = QgsRectangle(), int width = 0, int height = 0, int dpi = 96 );
 
     /**
-     * \brief   Returns the caption error text for the last error in this provider
+     * \brief Returns the caption error text for the last error in this provider
      *
      * If an operation returns 0 (e.g. draw()), this function
      * returns the text of the error associated with the failure.
      * Interactive users of this provider can then, for example,
      * call a QMessageBox to display the contents.
-     *
      */
     virtual QString lastErrorTitle() = 0;
 
@@ -377,10 +376,10 @@ class CORE_EXPORT QgsRasterDataProvider : public QgsDataProvider, public QgsRast
     /**
      * Turns on/off editing mode of the provider. When in editing mode, it is possible
      * to overwrite data of the provider using writeBlock() calls.
+     * \returns true if the switch to/from editing mode was successful
      * \note Only some providers support editing mode and even those may fail to turn
      * the underlying data source into editing mode, so it is necessary to check the return
      * value whether the operation was successful.
-     * \returns true if the switch to/from editing mode was successful
      * \see isEditable(), writeBlock()
      * \since QGIS 3.0
      */