Improve QgsCoordinateReferenceSystem documentation

Author: nyalldawson

python/core/qgscoordinatereferencesystem.sip

@@ -33,7 +33,7 @@ class QgsCoordinateReferenceSystem
 
     /** Use this constructor when you want to create a CRS object using
      *  a postgis SRID, an EpsgCrsId id or a QGIS CRS_ID.
-     * @note We encourage you to use EpsgCrsId, Wkt or Proj4 to describe CRS's in your code
+     * @note We encourage you to use EpsgCrsId, WKT or Proj4 to describe CRS's in your code
      * wherever possible. QGSI CRS_IDs are not guaranteed to be permanent / involatile.
      * @param theId The ID no valid for the chosen coordinate system id type
      * @param theType One of the types described in QgsCoordinateReferenceSystem::CrsType
@@ -53,27 +53,27 @@ class QgsCoordinateReferenceSystem
      */
     bool createFromOgcWmsCrs( QString theCrs );
 
-    /** Set up this srs by fetching the appropriate information from the
+    /** Set up this CRS by fetching the appropriate information from the
      * sqlite backend. First the system level read only srs.db will be checked
      * and then the users ~/.qgis/qgis.db database will be checked for a match.
      * @note Any members will be overwritten during this process.
      * @param theSrid The postgis SRID for the desired spatial reference system.
      */
     bool createFromSrid( const long theSrid );
 
-    /** Set up this srs using a Wkt spatial ref sys definition.
-     * The wkt will be converted to a proj4 string using OGR helper
-     * functions. After this the srs databasses will be searched for matches.
+    /** Set up this CRS using a WKT spatial ref sys definition.
+     * The WKT will be converted to a proj4 string using OGR helper
+     * functions. After this the SRS databases will be searched for matches.
      * First the system level read only srs.db will be checked
      * and then the users ~/.qgis/qgis.db database will be checked for a match.
      * @note Any members will be overwritten during this process.
-     * @note SRID and EpsgCrsId may be blank if no match can be found on srs db.
-     * @param theWkt The Wkt for the desired spatial reference system.
+     * @note SRID and EpsgCrsId may be blank if no match can be found on SRS db.
+     * @param theWkt The WKT for the desired spatial reference system.
      * @return bool TRUE if success else false
      */
     bool createFromWkt( const QString &theWkt );
 
-    /** Set up this srs by fetching the appropriate information from the
+    /** Set up this CRS by fetching the appropriate information from the
      * sqlite backend. If the srsid is < 100000, only the system srs.db
      * will be checked. If the srsid > 100000 the srs will be retrieved from
      * the ~/.qgis/qgis.db
@@ -83,7 +83,7 @@ class QgsCoordinateReferenceSystem
      */
     bool createFromSrsId( const long theSrsId );
 
-    /** Set up this srs by passing it a proj4 style formatted string.
+    /** Set up this CRS by passing it a proj4 style formatted string.
      * The string will be parsed and the projection and ellipsoid
      * members set and the remainder of the proj4 string will be stored
      * in the parameters member. The reason for this is so that we
@@ -94,7 +94,7 @@ class QgsCoordinateReferenceSystem
      *
      * We try to match the proj string to and srsid using the following logic:
      *
-     * - perform a whole text search on srs name (if not null). The srs name will
+     * - perform a whole text search on CRS name (if not null). The CRS name will
      *   have been set if this method has been delegated to from createFromWkt.
      * - if the above does not match perform a whole text search on proj4 string (if not null)
      * - if none of the above match convert the proj4 string to an OGR CRS
@@ -111,7 +111,7 @@ class QgsCoordinateReferenceSystem
      */
     bool createFromProj4( const QString &theProjString );
 
-    /** Set up this srs from a string definition, by default a WKT definition.  Otherwise
+    /** Set up this CRS from a string definition, by default a WKT definition.  Otherwise
      * the string defines a authority, followed by a colon, followed by the definition.
      * The authority can be one of "epsg", "postgis", "internal" for integer definitions,
      * and "wkt" or "proj4" for string definitions.  The implementation of each authority
@@ -120,7 +120,7 @@ class QgsCoordinateReferenceSystem
      */
     bool createFromString( const QString &theDefinition );
 
-    /** Set up this srs from a various text formats.
+    /** Set up this CRS from a various text formats.
      *
      * Valid formats: WKT string, "EPSG:n", "EPSGA:n", "AUTO:proj_id,unit_id,lon0,lat0",
      * "urn:ogc:def:crs:EPSG::n", PROJ.4 string, filename (with WKT, XML or PROJ.4 string),
@@ -145,7 +145,7 @@ class QgsCoordinateReferenceSystem
      */
     static void setupESRIWktFix();
 
-    /** Find out whether this CRS is correctly initialised and usable */
+    /** Returns whether this CRS is correctly initialised and usable */
     bool isValid() const;
 
     /** Perform some validation on this CRS. If the sts doesn't validate the
@@ -155,7 +155,7 @@ class QgsCoordinateReferenceSystem
      * if that involves resorting to a hard coded default of geocs:wgs84.
      *
      * @note It is not usually necessary to use this function, unless you
-     * are trying to force this srs to be valid.
+     * are trying to force this CRS to be valid.
      */
     void validate();
 
@@ -219,65 +219,75 @@ class QgsCoordinateReferenceSystem
 
     // Accessors -----------------------------------
 
-    /** Get the SrsId - if possible
-    *  @return  long theSrsId The internal sqlite3 srs.db primary key for this srs
-    */
+    /** Returns the SrsId, if available.
+     *  @return the internal sqlite3 srs.db primary key for this srs
+     * @see postgisSrid()
+     */
     long srsid() const;
 
-    /** Get the postgis srid for this srs
-     * @return  long theSRID the Postgis spatial_ref_sys identifier for this srs (defaults to 0)
+    /** Returns PostGIS SRID for the CRS.
+     * @return the PostGIS spatial_ref_sys identifier for this CRS (defaults to 0)
      */
     long postgisSrid() const;
 
-    /** Get the authority identifier for this srs
-     * @return  QString the Authority identifier for this srs
+    /** Returns the authority identifier for the CRS, which includes both the authority (eg EPSG)
+     * and the CRS number (eg 4326). This is the best method to use when showing a very short CRS
+     * identifier to a user, eg "EPSG:4326".
+     * @returns the authority identifier for this CRS
+     * @see description()
      */
     QString authid() const;
 
-    /** Get the Description
-     * @return  QString the Description A textual description of the srs.
-     * @note A zero length string will be returned if the description is uninitialised
+    /** Returns the descriptive name of the CRS, eg "WGS 84" or "GDA 94 / Vicgrid94". In most
+     * cases this is the best method to use when showing a friendly identifier for the CRS to a
+     * user.
+     * @returns descriptive name of the CRS
+     * @note an empty string will be returned if the description is not available for the CRS
+     * @see authid()
      */
     QString description() const;
 
-    /** Get the Projection Acronym
-     * @return  QString theProjectionAcronym The official proj4 acronym for the projection family
-     * @note A zero length string will be returned if the projectionAcronym is uninitialised
+    /** Returns the projection acronym for the projection used by the CRS.
+     * @returns the official proj4 acronym for the projection family
+     * @note an empty string will be returned if the projectionAcronym is not available for the CRS
+     * @see ellipsoidAcronym()
      */
     QString projectionAcronym() const;
 
-    /** Get the Ellipsoid Acronym
-     * @return  QString theEllipsoidAcronym The official proj4 acronym for the ellipoid
-     * @note A zero length string will be returned if the ellipsoidAcronym is uninitialised
+    /** Returns the ellipsoid acronym for the ellipsoid used by the CRS.
+     * @returns the official proj4 acronym for the ellipoid
+     * @note an empty string will be returned if the ellipsoidAcronym is not available for the CRS
+     * @see projectionAcronym()
      */
     QString ellipsoidAcronym() const;
 
-    /** A helper to get an wkt representation of this srs
-     * @return string containing Wkt of the srs
+    /** Returns a WKT representation of this CRS.
+     * @return string containing WKT of the CRS
+     * @see toProj4()
      */
     QString toWkt() const;
 
-    /** Get the Proj Proj4 string representation of this srs.
+    /** Returns a Proj4 string representation of this CRS.
      * If proj and ellps keys are found in the parameters,
-     * they will be stripped out and the Projection and ellipsoid acronyms will be
+     * they will be stripped out and the projection and ellipsoid acronyms will be
      * overridden with these.
-     * @return  QString theProj4String Proj4 format specifies that define this srs.
-     * @note A zero length string will be returned if the toProj4 is uninitialised
+     * @return Proj4 format string that defines this CRS.
+     * @note an empty string will be returned if the CRS could not be represented by a Proj4 string
+     * @see toWkt()
      */
     QString toProj4() const;
 
-    /** Get this Geographic? flag
-     * @return  bool theGeoFlag Whether this is a geographic or projected coordinate system
+    /** Returns whether the CRS is a geographic CRS.
+     * @returns true if CRS is geographic, or false if it is a projected CRS
      */
     bool geographicFlag() const;
 
-    /** Return if axis is inverted (eg. for WMS 1.3)
-     * @return  bool Whether this is crs axis is inverted
+    /** Returns whether axis is inverted (eg. for WMS 1.3) for the CRS.
+     * @returns true if CRS axis is inverted
      */
     bool axisInverted() const;
 
-    /** Get the units that the projection is in
-     * @return QGis::UnitType that gives the units for the coordinate system
+    /** Returns the units for the projection used by the CRS.
      */
     QGis::UnitType mapUnits() const;