geometry sip sync and some cosmetics

Author: jef-n

python/core/geometry/qgsabstractgeometryv2.sip

@@ -70,46 +70,167 @@ class QgsAbstractGeometryV2
     QgsAbstractGeometryV2( const QgsAbstractGeometryV2& geom );
     //virtual QgsAbstractGeometryV2& operator=( const QgsAbstractGeometryV2& geom );
 
+    /** Clones the geometry by performing a deep copy
+     */
     virtual QgsAbstractGeometryV2* clone() const = 0;
+
+    /** Clears the geometry, ie reset it to a null geometry
+     */
     virtual void clear() = 0;
 
+    /** Returns the minimal bounding box for the geometry
+     */
     QgsRectangle boundingBox() const;
 
+    /** Calculates the minimal bounding box for the geometry. Derived classes should override this method
+     * to return the correct bounding box.
+     */
+    virtual QgsRectangle calculateBoundingBox() const;
+
     //mm-sql interface
+    /** Returns the inherent dimension of the geometry. For example, this is 0 for a point geometry,
+     * 1 for a linestring and 2 for a polygon.
+     */
     virtual int dimension() const = 0;
     //virtual int coordDim() const { return mCoordDimension; }
+
+    /** Returns a unique string representing the geometry type.
+     * @see wkbType
+     * @see wktTypeStr
+     */
     virtual QString geometryType() const = 0;
+
+    /** Returns the WKB type of the geometry.
+     * @see geometryType
+     * @see wktTypeStr
+     */
     QgsWKBTypes::Type wkbType() const;
+
+    /** Returns the WKT type string of the geometry.
+     * @see geometryType
+     * @see wkbType
+     */
     QString wktTypeStr() const;
+
+    /** Returns true if the geometry is 3D and contains a z-value.
+     * @see isMeasure
+     */
     bool is3D() const;
+
+    /** Returns true if the geometry contains m values.
+     * @see is3D
+     */
     bool isMeasure() const;
 
     //import
+
+    /** Sets the geometry from a WKB string.
+     * @see fromWkt
+     */
     virtual bool fromWkb( const unsigned char * wkb ) = 0;
+
+    /** Sets the geometry from a WKT string.
+     * @see fromWkb
+     */
     virtual bool fromWkt( const QString& wkt ) = 0;
 
     //export
+
+    /** Returns the size of the WKB representation of the geometry.
+     * @see asWkb
+     */
     virtual int wkbSize() const = 0;
+
+    /** Returns a WKB representation of the geometry.
+     * @param binarySize will be set to the size of the returned WKB string
+     * @see wkbSize
+     * @see asWkt
+     * @see asGML2
+     * @see asGML3
+     * @see asJSON
+     */
     virtual unsigned char* asWkb( int& binarySize ) const = 0;
+
+    /** Returns a WKT representation of the geometry.
+     * @param precision number of decimal places for coordinates
+     * @see asWkb
+     * @see asGML2
+     * @see asGML3
+     * @see asJSON
+     */
     virtual QString asWkt( int precision = 17 ) const = 0;
+
+    /** Returns a GML2 representation of the geometry.
+     * @param doc DOM document
+     * @param precision number of decimal places for coordinates
+     * @param ns XML namespace
+     * @see asWkb
+     * @see asWkt
+     * @see asGML3
+     * @see asJSON
+     */
     virtual QDomElement asGML2( QDomDocument& doc, int precision = 17, const QString& ns = "gml" ) const = 0;
+
+    /** Returns a GML3 representation of the geometry.
+     * @param doc DOM document
+     * @param precision number of decimal places for coordinates
+     * @param ns XML namespace
+     * @see asWkb
+     * @see asWkt
+     * @see asGML2
+     * @see asJSON
+     */
     virtual QDomElement asGML3( QDomDocument& doc, int precision = 17, const QString& ns = "gml" ) const = 0;
-    virtual QString asJSON( int precision = 17 ) const = 0;
 
-    virtual QgsRectangle calculateBoundingBox() const;
+    /** Returns a GeoJSON representation of the geometry.
+     * @param precision number of decimal places for coordinates
+     * @see asWkb
+     * @see asWkt
+     * @see asGML2
+     * @see asGML3
+     */
+    virtual QString asJSON( int precision = 17 ) const = 0;
 
     //render pipeline
+
+    /** Transforms the geometry using a coordinate transform
+     * @param ct coordinate transform
+       @param d transformation direction
+     */
     virtual void transform( const QgsCoordinateTransform& ct, QgsCoordinateTransform::TransformDirection d = QgsCoordinateTransform::ForwardTransform ) = 0;
+
+    /** Transforms the geometry using a QTransform object
+     * @param t QTransform transformation
+     */
     virtual void transform( const QTransform& t ) = 0;
+
+
     //virtual void clip( const QgsRectangle& rect );
+
+    /** Draws the geometry using the specified QPainter.
+     * @param p destination QPainter
+     */
     virtual void draw( QPainter& p ) const = 0;
 
     /** Returns next vertex id and coordinates
-    @return false if at end*/
+     * @param id initial value should be the starting vertex id. The next vertex id will be stored
+     * in this variable if found.
+     * @param vertex container for found node
+     * @return false if at end
+     */
     virtual bool nextVertex( QgsVertexId& id, QgsPointV2& vertex ) const = 0;
 
+    /** Retrieves the sequence of geometries, rings and nodes.
+     * @param coord destination for coordinate sequence.
+     */
     virtual void coordinateSequence( QList< QList< QList< QgsPointV2 > > >& coord /Out/ ) const = 0;
+
+    /** Returns the number of nodes contained in the geometry
+     */
     int nCoordinates() const;
+
+    /** Returns the point corresponding to a specified vertex id
+     */
     virtual QgsPointV2 vertexAt( const QgsVertexId& id ) const = 0;
 
     /** Searches for the closest segment of the geometry to a given point.
@@ -121,11 +242,34 @@ class QgsAbstractGeometryV2
      * @param epsilon epsilon for segment snapping
      * @returns squared distance to closest segment
      */
-    virtual double closestSegment( const QgsPointV2& pt, QgsPointV2& segmentPt,  QgsVertexId& vertexAfter, bool* leftOf, double epsilon ) const = 0;
+    virtual double closestSegment( const QgsPointV2& pt, QgsPointV2& segmentPt, QgsVertexId& vertexAfter, bool* leftOf, double epsilon ) const = 0;
 
     //low-level editing
+
+    /** Inserts a vertex into the geometry
+     * @param position vertex id for position of inserted vertex
+     * @param vertex vertex to insert
+     * @returns true if insert was successful
+     * @see moveVertex
+     * @see deleteVertex
+     */
     virtual bool insertVertex( const QgsVertexId& position, const QgsPointV2& vertex ) = 0;
+
+    /** Moves a vertex within the geometry
+     * @param position vertex id for vertex to move
+     * @param newPos new position of vertex
+     * @returns true if move was successful
+     * @see insertVertex
+     * @see deleteVertex
+     */
     virtual bool moveVertex( const QgsVertexId& position, const QgsPointV2& newPos ) = 0;
+
+    /** Deletes a vertex within the geometry
+     * @param position vertex id for vertex to delete
+     * @returns true if delete was successful
+     * @see insertVertex
+     * @see moveVertex
+     */
     virtual bool deleteVertex( const QgsVertexId& position ) = 0;
 
     /** Returns the length of the geometry.
@@ -146,15 +290,20 @@ class QgsAbstractGeometryV2
      */
     virtual double area() const;
 
-    /** Returns the centroid of the geometry*/
+    /** Returns the centroid of the geometry */
     virtual QgsPointV2 centroid() const;
 
     /** Returns true if the geometry is empty
      */
     bool isEmpty() const;
 
+    /** Returns true if the geometry contains curved segments
+     */
     virtual bool hasCurvedSegments() const;
-    /** Returns a geometry without curves. Caller takes ownership*/
+
+    /** Returns a version of the geometry without curves. Caller takes ownership of
+     * the returned geometry.
+     */
     virtual QgsAbstractGeometryV2* segmentize() const /Factory/;
 
     /** Returns approximate angle at a vertex. This is usually the average angle between adjacent
@@ -165,8 +314,8 @@ class QgsAbstractGeometryV2
     */
     virtual double vertexAngle( const QgsVertexId& vertex ) const = 0;
 
-    virtual int vertexCount(int part = 0, int ring = 0) const = 0;
-    virtual int ringCount(int part = 0) const = 0;
+    virtual int vertexCount( int part = 0, int ring = 0 ) const = 0;
+    virtual int ringCount( int part = 0 ) const = 0;
 
     /** Returns count of parts contained in the geometry.
      * @see vertexCount
@@ -178,15 +327,17 @@ class QgsAbstractGeometryV2
      * @param zValue initial z-value for all nodes
      * @returns true on success
      * @note added in QGIS 2.12
-     * @see addMValue
+     * @see dropZValue()
+     * @see addMValue()
      */
     virtual bool addZValue( double zValue = 0 ) = 0;
 
     /** Adds a measure to the geometry, initialized to a preset value.
      * @param mValue initial m-value for all nodes
      * @returns true on success
      * @note added in QGIS 2.12
-     * @see addZValue
+     * @see dropMValue()
+     * @see addZValue()
      */
     virtual bool addMValue( double mValue = 0 ) = 0;
 

python/core/geometry/qgscircularstringv2.sip

@@ -29,33 +29,71 @@ class QgsCircularStringV2: public QgsCurveV2
     QString asJSON( int precision = 17 ) const;
 
     int numPoints() const;
+
+    /** Returns the point at index i within the circular string.
+     */
     QgsPointV2 pointN( int i ) const;
+
+    /**
+     * @copydoc QgsCurveV2::points()
+     */
     void points( QList<QgsPointV2>& pts ) const;
-    void setPoints( const QList<QgsPointV2>& points );
 
+    /** Sets the circular string's points
+     */
+    void setPoints( const QList<QgsPointV2>& points );
 
-    //curve interface
+    /**
+     * @copydoc QgsAbstractGeometryV2::length()
+     */
     virtual double length() const;
+
+    /**
+     * @copydoc QgsCurveV2::startPoint()
+     */
     virtual QgsPointV2 startPoint() const;
+    /**
+     * @copydoc QgsCurveV2::endPoint()
+     */
     virtual QgsPointV2 endPoint() const;
+    /**
+     * @copydoc QgsCurveV2::curveToLine()
+     */
     virtual QgsLineStringV2* curveToLine() const;
 
     void draw( QPainter& p ) const;
+
+    /** Transforms the geometry using a coordinate transform
+     * @param ct coordinate transform
+     * @param d transformation direction
+     */
     void transform( const QgsCoordinateTransform& ct, QgsCoordinateTransform::TransformDirection d = QgsCoordinateTransform::ForwardTransform );
     void transform( const QTransform& t );
-    //void clip( const QgsRectangle& rect );
     void addToPainterPath( QPainterPath& path ) const;
+
+    /**
+     * @copydoc QgsCurveV2::drawAsPolygon()
+     */
     void drawAsPolygon( QPainter& p ) const;
 
     virtual bool insertVertex( const QgsVertexId& position, const QgsPointV2& vertex );
     virtual bool moveVertex( const QgsVertexId& position, const QgsPointV2& newPos );
     virtual bool deleteVertex( const QgsVertexId& position );
 
     double closestSegment( const QgsPointV2& pt, QgsPointV2& segmentPt,  QgsVertexId& vertexAfter, bool* leftOf, double epsilon ) const;
+    /**
+     * @copydoc QgsCurveV2::pointAt()
+     */
     bool pointAt( int i, QgsPointV2& vertex, QgsVertexId::VertexType& type ) const;
 
+    /**
+     * @copydoc QgsCurveV2::sumUpArea()
+     */
     void sumUpArea( double& sum ) const;
 
+    /**
+     * @copydoc QgsAbstractGeometryV2::hasCurvedSegments()
+     */
     bool hasCurvedSegments() const;
 
     /** Returns approximate rotation angle for a vertex. Usually average angle between adjacent segments.

python/core/geometry/qgscompoundcurvev2.sip

@@ -37,17 +37,33 @@ class QgsCompoundCurveV2: public QgsCurveV2
     virtual void points( QList<QgsPointV2>& pts ) const;
     virtual int numPoints() const;
     virtual QgsLineStringV2* curveToLine() const;
+
+    /** Returns the number of curves in the geometry.
+     */
     int nCurves() const;
+
+    /** Returns the curve at the specified index.
+     */
     const QgsCurveV2* curveAt( int i ) const;
 
-    /** Adds curve (takes ownership)*/
+    /** Adds a curve to the geometr (takes ownership)
+     */
     void addCurve( QgsCurveV2* c /Transfer/ );
+
+    /** Removes a curve from the geometry.
+     * @param i index of curve to remove
+     */
     void removeCurve( int i );
+
+    /** Adds a vertex to the end of the geometry.
+     */
     void addVertex( const QgsPointV2& pt );
-    /** Returns closed ring based on curve (connects to start point if not already done)*/
-    void close();
 
     void draw( QPainter& p ) const;
+    /** Transforms the geometry using a coordinate transform
+     * @param ct coordinate transform
+       @param d transformation direction
+     */
     void transform( const QgsCoordinateTransform& ct, QgsCoordinateTransform::TransformDirection d = QgsCoordinateTransform::ForwardTransform );
     void transform( const QTransform& t );
     void addToPainterPath( QPainterPath& path ) const;
@@ -58,10 +74,13 @@ class QgsCompoundCurveV2: public QgsCurveV2
     virtual bool deleteVertex( const QgsVertexId& position );
 
     virtual double closestSegment( const QgsPointV2& pt, QgsPointV2& segmentPt,  QgsVertexId& vertexAfter, bool* leftOf, double epsilon ) const;
-    bool pointAt( int i, QgsPointV2& vertex, QgsVertexId::VertexType& type ) const;
+    bool pointAt( int node, QgsPointV2& point, QgsVertexId::VertexType& type ) const;
 
     void sumUpArea( double& sum ) const;
 
+    /** Appends first point if not already closed.*/
+    void close();
+
     bool hasCurvedSegments() const;
 
     /** Returns approximate rotation angle for a vertex. Usually average angle between adjacent segments.