Skip to content
Permalink
Browse files

[doxygen] fix badly placed \returns

  • Loading branch information
3nids committed Dec 16, 2017
1 parent e6f657c commit 281392b103b2f3edfc57e03b14eb1952dd10fa64
@@ -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
@@ -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;

@@ -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,
@@ -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;

@@ -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();

@@ -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 );

@@ -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;
@@ -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();

@@ -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 );

@@ -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;

@@ -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 );

@@ -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 );

@@ -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
*/

0 comments on commit 281392b

Please sign in to comment.
You can’t perform that action at this time.