Updates to api docs and some api consistency cleanups

git-svn-id: http://svn.osgeo.org/qgis/trunk/qgis@9213 c8812cc2-4d05-0410-92ff-de0c093fc19c

Author: timlinux

python/core/qgsgeometry.sip

@@ -126,15 +126,15 @@ class QgsGeometry
      *  these error conditions.  (Or maybe we add another method to this
      *  object to help make the distinction?)
      */
-	bool insertVertexBefore(double x, double y, int beforeVertex);
+	bool insertVertex(double x, double y, int beforeVertex);
 
     /** Moves the vertex at the given position number,
      *  ring and item (first number is index 0)
      *  to the given coordinates.
      *  Returns FALSE if atVertex does not correspond to a valid vertex
      *  on this geometry 
      */
-	bool moveVertexAt(double x, double y, int atVertex);
+	bool moveVertex(double x, double y, int atVertex);
 
 	/** Deletes the vertex at the given position number,
      *  ring and item (first number is index 0)
@@ -146,7 +146,7 @@ class QgsGeometry
      *  these error conditions.  (Or maybe we add another method to this
      *  object to help make the distinction?)
      */
-	bool deleteVertexAt(int atVertex);
+	bool deleteVertex(int atVertex);
 
     /**
      *  Returns coordinates of a vertex.

python/core/qgsvectordataprovider.sip

@@ -221,7 +221,7 @@ class QgsVectorDataProvider : QgsDataProvider
       /**
        * Returns the index of a field name or -1 if the field does not exist
        */
-      int indexFromFieldName(const QString& fieldName) const;
+      int fieldNameIndex(const QString& fieldName) const;
 
       /**
        * Return list of indexes to fetch all attributes in getNextFeature()
@@ -235,6 +235,6 @@ class QgsVectorDataProvider : QgsDataProvider
        * Set whether provider should return also features that don't have
        * associated geometry. FALSE by default
        */
-      void setFetchFeaturesWithoutGeom(bool fetch);
+      void enableGeometrylessFeatures(bool fetch);
 
 };

python/core/qgsvectorlayer.sip

@@ -165,18 +165,18 @@ public:
    *  in the given ring, item (first number is index 0), and feature
    *  Not meaningful for Point geometries
    */
-  bool insertVertexBefore(double x, double y, int atFeatureId, int beforeVertex);
+  bool insertVertex(double x, double y, int atFeatureId, int beforeVertex);
 
   /** Moves the vertex at the given position number,
    *  ring and item (first number is index 0), and feature
    *  to the given coordinates
    */
-  bool moveVertexAt(double x, double y, int atFeatureId, int atVertex);
+  bool moveVertex(double x, double y, int atFeatureId, int atVertex);
 
   /** Deletes the vertex at the given position number,
    *  ring and item (first number is index 0), and feature
    */
-  bool deleteVertexAt(int atFeatureId, int atVertex);
+  bool deleteVertex(int atFeatureId, int atVertex);
 
   /** Deletes the selected features
    *  @return true in case of success and false otherwise

scripts/astyle.sh

@@ -32,7 +32,7 @@ $ARTISTIC_STYLE_OPTIONS \
 --unpad=paren"
 
 for f in "$@"; do
-	flip -ub "$f" 
+	#flip -ub "$f" 
     	#qgsloggermig.pl "$f"
 	astyle $ARTISTIC_STYLE_OPTIONS "$f"
 done

src/app/qgsmaptooladdvertex.cpp

@@ -98,7 +98,7 @@ void QgsMapToolAddVertex::canvasReleaseEvent( QMouseEvent * e )
       QList<QgsSnappingResult>::iterator sr_it = mRecentSnappingResults.begin();
       for ( ; sr_it != mRecentSnappingResults.end(); ++sr_it )
       {
-        vlayer->insertVertexBefore( snappedPointLayerCoord.x(), snappedPointLayerCoord.y(), sr_it->snappedAtGeometry, sr_it->afterVertexNr );
+        vlayer->insertVertex( snappedPointLayerCoord.x(), snappedPointLayerCoord.y(), sr_it->snappedAtGeometry, sr_it->afterVertexNr );
       }
     }
   }

src/app/qgsmaptooldeletevertex.cpp

@@ -81,7 +81,7 @@ void QgsMapToolDeleteVertex::canvasReleaseEvent( QMouseEvent * e )
     QList<QgsSnappingResult>::iterator sr_it = mRecentSnappingResults.begin();
     for ( ; sr_it != mRecentSnappingResults.end(); ++sr_it )
     {
-      vlayer->deleteVertexAt( sr_it->snappedAtGeometry, sr_it->snappedVertexNr );
+      vlayer->deleteVertex( sr_it->snappedAtGeometry, sr_it->snappedVertexNr );
     }
   }
 

src/app/qgsmaptoolmovevertex.cpp

@@ -168,7 +168,7 @@ void QgsMapToolMoveVertex::canvasReleaseEvent( QMouseEvent * e )
     QList<QgsSnappingResult>::iterator sr_it = mRecentSnappingResults.begin();
     for ( ; sr_it != mRecentSnappingResults.end(); ++sr_it )
     {
-      if ( !vlayer->moveVertexAt( snappedPointLayerCoord.x(), snappedPointLayerCoord.y(), sr_it->snappedAtGeometry, sr_it->snappedVertexNr ) )
+      if ( !vlayer->moveVertex( snappedPointLayerCoord.x(), snappedPointLayerCoord.y(), sr_it->snappedAtGeometry, sr_it->snappedVertexNr ) )
       {
         //error
       }

src/app/qgsuniquevaluedialog.cpp

@@ -149,7 +149,7 @@ void QgsUniqueValueDialog::apply()
   QgsVectorDataProvider *provider = dynamic_cast<QgsVectorDataProvider *>( mVectorLayer->dataProvider() );
   if ( provider )
   {
-    int fieldIndex = provider->indexFromFieldName( mClassificationComboBox->currentText() );
+    int fieldIndex = provider->fieldNameIndex( mClassificationComboBox->currentText() );
     if ( fieldIndex != -1 )
     {
       renderer->setClassificationField( fieldIndex );
@@ -292,7 +292,7 @@ void QgsUniqueValueDialog::changeClassificationAttribute()
   QgsVectorDataProvider *provider = dynamic_cast<QgsVectorDataProvider *>( mVectorLayer->dataProvider() );
   if ( provider )
   {
-    int nr = provider->indexFromFieldName( attributeName );
+    int nr = provider->fieldNameIndex( attributeName );
     if ( nr == -1 )
     {
       return;

src/core/qgsgeometry.cpp

@@ -1147,7 +1147,7 @@ void QgsGeometry::adjacentVerticies( int atVertex, int& beforeVertex, int& after
 
 
 
-bool QgsGeometry::insertVertexBefore( double x, double y,
+bool QgsGeometry::insertVertex( double x, double y,
                                       int beforeVertex,
                                       const GEOSCoordSequence*  old_sequence,
                                       GEOSCoordSequence** new_sequence )
@@ -1199,7 +1199,7 @@ bool QgsGeometry::insertVertexBefore( double x, double y,
   return inserted;
 }
 
-bool QgsGeometry::moveVertexAt( double x, double y, int atVertex )
+bool QgsGeometry::moveVertex( double x, double y, int atVertex )
 {
   int vertexnr = atVertex;
 
@@ -1448,7 +1448,7 @@ bool QgsGeometry::moveVertexAt( double x, double y, int atVertex )
   }
 }
 
-bool QgsGeometry::deleteVertexAt( int atVertex )
+bool QgsGeometry::deleteVertex( int atVertex )
 {
   int vertexnr = atVertex;
   bool success = false;
@@ -1775,7 +1775,7 @@ bool QgsGeometry::deleteVertexAt( int atVertex )
   }
 }
 
-bool QgsGeometry::insertVertexBefore( double x, double y, int beforeVertex )
+bool QgsGeometry::insertVertex( double x, double y, int beforeVertex )
 {
   int vertexnr = beforeVertex;
   bool success = false;

src/core/qgsgeometry.h

@@ -164,15 +164,15 @@ class CORE_EXPORT QgsGeometry
      *  these error conditions.  (Or maybe we add another method to this
      *  object to help make the distinction?)
      */
-    bool insertVertexBefore( double x, double y, int beforeVertex );
+    bool insertVertex( double x, double y, int beforeVertex );
 
     /** Moves the vertex at the given position number
      *  and item (first number is index 0)
      *  to the given coordinates.
      *  Returns FALSE if atVertex does not correspond to a valid vertex
      *  on this geometry
      */
-    bool moveVertexAt( double x, double y, int atVertex );
+    bool moveVertex( double x, double y, int atVertex );
 
     /** Deletes the vertex at the given position number and item
      *  (first number is index 0)
@@ -184,7 +184,7 @@ class CORE_EXPORT QgsGeometry
      *  these error conditions.  (Or maybe we add another method to this
      *  object to help make the distinction?)
      */
-    bool deleteVertexAt( int atVertex );
+    bool deleteVertex( int atVertex );
 
     /**
      *  Returns coordinates of a vertex.
@@ -362,7 +362,7 @@ class CORE_EXPORT QgsGeometry
      *  Returns FALSE if beforeVertex does not correspond to a valid vertex number
      *  on the Coordinate Sequence.
      */
-    bool insertVertexBefore( double x, double y,
+    bool insertVertex( double x, double y,
                              int beforeVertex,
                              const GEOSCoordSequence*  old_sequence,
                              GEOSCoordSequence** new_sequence );

src/core/qgsvectordataprovider.cpp

@@ -218,7 +218,7 @@ QString QgsVectorDataProvider::capabilitiesString() const
 }
 
 
-int QgsVectorDataProvider::indexFromFieldName( const QString& fieldName ) const
+int QgsVectorDataProvider::fieldNameIndex( const QString& fieldName ) const
 {
   const QgsFieldMap &theFields = fields();
 
@@ -243,7 +243,7 @@ QgsAttributeList QgsVectorDataProvider::allAttributesList()
   return list;
 }
 
-void QgsVectorDataProvider::setFetchFeaturesWithoutGeom( bool fetch )
+void QgsVectorDataProvider::enableGeometrylessFeatures( bool fetch )
 {
   mFetchFeaturesWithoutGeom = fetch;
 }

src/core/qgsvectordataprovider.h

@@ -32,7 +32,13 @@ class QTextCodec;
 typedef QMap<QString, QString> QgsNewAttributesMap;
 typedef QMap<QString, QVariant::Type> QgsNativeTypeMap;
 
-/** Base class for vector data providers
+/** \ingroup core
+ * This is the base class for vector data providers.
+ *
+ * Data providers abstract the retrieval and writing (where supported) 
+ * of feature and attrubute information from a spatial datasource.
+ *
+ *
  */
 class CORE_EXPORT QgsVectorDataProvider : public QgsDataProvider
 {
@@ -95,9 +101,9 @@ class CORE_EXPORT QgsVectorDataProvider : public QgsDataProvider
 
     /**
      * Gets the feature at the given feature ID.
-     * @param featureId id of the feature
-     * @param feature feature which will receive the data
-     * @param fetchGeoemtry if true, geometry will be fetched from the provider
+     * @param featureId of the feature to be returned
+     * @param feature which will receive the data
+     * @param fetchGeometry flag which if true, will cause the geometry to be fetched from the provider
      * @param fetchAttributes a list containing the indexes of the attribute fields to copy
      * @return True when feature was found, otherwise false
      *
@@ -138,6 +144,7 @@ class CORE_EXPORT QgsVectorDataProvider : public QgsDataProvider
     /**
      * Return a map of indexes with field names for this layer
      * @return map of fields
+     * @see QgsFieldMap
      */
     virtual const QgsFieldMap &fields() const = 0;
 
@@ -151,7 +158,7 @@ class CORE_EXPORT QgsVectorDataProvider : public QgsDataProvider
     virtual void reset() = 0;
 
     /**
-     * Returns the minimum value of an attributs
+     * Returns the minimum value of an attribute
      * @param index the index of the attribute
      *
      * Default implementation walks all numeric attributes and caches minimal
@@ -161,7 +168,7 @@ class CORE_EXPORT QgsVectorDataProvider : public QgsDataProvider
     virtual QVariant minimumValue( int index );
 
     /**
-     * Returns the maximum value of an attributs
+     * Returns the maximum value of an attribute
      * @param index the index of the attribute
      *
      * Default implementation walks all numeric attributes and caches minimal
@@ -186,7 +193,7 @@ class CORE_EXPORT QgsVectorDataProvider : public QgsDataProvider
     virtual bool addFeatures( QgsFeatureList &flist );
 
     /**
-     * Deletes a feature
+     * Deletes one or more features
      * @param id list containing feature ids to delete
      * @return true in case of success and false in case of failure
      */
@@ -220,9 +227,10 @@ class CORE_EXPORT QgsVectorDataProvider : public QgsDataProvider
 
     /**
      * Changes geometries of existing features
-     * @param geometry_map   A std::map containing the feature IDs to change the geometries of.
-     *                       the second map parameter being the new geometries themselves
-     * @return               true in case of success and false in case of failure
+     * @param geometry_map   A QgsGeometryMap whose index contains the feature IDs 
+     *                       that will have their geometries changed.
+     *                       The second map parameter being the new geometries themselves
+     * @return               True in case of success and false in case of failure
      */
     virtual bool changeGeometryValues( QgsGeometryMap & geometry_map );
 
@@ -257,7 +265,7 @@ class CORE_EXPORT QgsVectorDataProvider : public QgsDataProvider
     /**
      * Returns the index of a field name or -1 if the field does not exist
      */
-    int indexFromFieldName( const QString& fieldName ) const;
+    int fieldNameIndex( const QString& fieldName ) const;
 
     /**
      * Return list of indexes to fetch all attributes in getNextFeature()
@@ -268,10 +276,10 @@ class CORE_EXPORT QgsVectorDataProvider : public QgsDataProvider
     const QgsNativeTypeMap &supportedNativeTypes() const;
 
     /**
-     * Set whether provider should return also features that don't have
+     * Set whether provider should also return features that don't have
      * associated geometry. FALSE by default
      */
-    void setFetchFeaturesWithoutGeom( bool fetch );
+    void enableGeometrylessFeatures( bool fetch );
 
   protected:
     QVariant convertValue( QVariant::Type type, QString value );

src/core/qgsvectorfilewriter.h

@@ -29,7 +29,8 @@ typedef void *OGRGeometryH;
 
 class QTextCodec;
 
-/**
+/** \ingroup core
+  * A convenience class for writing vector files to disk.
  There are two possibilities how to use this class:
  1. static call to QgsVectorFileWriter::writeAsShapefile(...) which saves the whole vector layer
  2. create an instance of the class and issue calls to addFeature(...)

src/core/qgsvectorlayer.cpp

@@ -1433,7 +1433,7 @@ bool QgsVectorLayer::addFeature( QgsFeature& f, bool alsoUpdateExtent )
 }
 
 
-bool QgsVectorLayer::insertVertexBefore( double x, double y, int atFeatureId, int beforeVertex )
+bool QgsVectorLayer::insertVertex( double x, double y, int atFeatureId, int beforeVertex )
 {
   if ( !mEditable )
   {
@@ -1453,7 +1453,7 @@ bool QgsVectorLayer::insertVertexBefore( double x, double y, int atFeatureId, in
       mChangedGeometries[atFeatureId] = mCachedGeometries[atFeatureId];
     }
 
-    mChangedGeometries[atFeatureId].insertVertexBefore( x, y, beforeVertex );
+    mChangedGeometries[atFeatureId].insertVertex( x, y, beforeVertex );
 
     setModified( true, true ); // only geometry was changed
 
@@ -1463,7 +1463,7 @@ bool QgsVectorLayer::insertVertexBefore( double x, double y, int atFeatureId, in
 }
 
 
-bool QgsVectorLayer::moveVertexAt( double x, double y, int atFeatureId, int atVertex )
+bool QgsVectorLayer::moveVertex( double x, double y, int atFeatureId, int atVertex )
 {
   if ( !mEditable )
   {
@@ -1482,7 +1482,7 @@ bool QgsVectorLayer::moveVertexAt( double x, double y, int atFeatureId, int atVe
       mChangedGeometries[atFeatureId] = mCachedGeometries[atFeatureId];
     }
 
-    mChangedGeometries[atFeatureId].moveVertexAt( x, y, atVertex );
+    mChangedGeometries[atFeatureId].moveVertex( x, y, atVertex );
 
     setModified( true, true ); // only geometry was changed
 
@@ -1492,7 +1492,7 @@ bool QgsVectorLayer::moveVertexAt( double x, double y, int atFeatureId, int atVe
 }
 
 
-bool QgsVectorLayer::deleteVertexAt( int atFeatureId, int atVertex )
+bool QgsVectorLayer::deleteVertex( int atFeatureId, int atVertex )
 {
   if ( !mEditable )
   {
@@ -1511,7 +1511,7 @@ bool QgsVectorLayer::deleteVertexAt( int atFeatureId, int atVertex )
       mChangedGeometries[atFeatureId] = mCachedGeometries[atFeatureId];
     }
 
-    mChangedGeometries[atFeatureId].deleteVertexAt( atVertex );
+    mChangedGeometries[atFeatureId].deleteVertex( atVertex );
 
     setModified( true, true ); // only geometry was changed
 
@@ -3167,7 +3167,7 @@ int QgsVectorLayer::insertSegmentVerticesForSnap( const QList<QgsSnappingResult>
     if ( it->snappedVertexNr == -1 ) // segment snap
     {
       layerPoint = it->snappedVertex;
-      if ( !insertVertexBefore( layerPoint.x(), layerPoint.y(), it->snappedAtGeometry, it->afterVertexNr ) )
+      if ( !insertVertex( layerPoint.x(), layerPoint.y(), it->snappedAtGeometry, it->afterVertexNr ) )
       {
         returnval = 3;
       }