Fix QgsGeometry.fromPolygonXY docs

Fixes #45099
qgis · Sep 20, 2021 · 3d599fe · 3d599fe
1 parent 30a56ac
commit 3d599fe
Show file tree

Hide file tree

Showing 2 changed files with 56 additions and 6 deletions.
diff --git a/python/core/auto_generated/geometry/qgsgeometry.sip.in b/python/core/auto_generated/geometry/qgsgeometry.sip.in
@@ -193,16 +193,35 @@ a LineStringZ type.
 
     static QgsGeometry fromMultiPolylineXY( const QgsMultiPolylineXY &multiline );
 %Docstring
-Creates a new geometry from a :py:class:`QgsMultiPolylineXY` object
+Creates a new geometry from a :py:class:`QgsMultiPolylineXY` object.
 %End
+
+
     static QgsGeometry fromPolygonXY( const QgsPolygonXY &polygon );
 %Docstring
-Creates a new geometry from a :py:class:`QgsPolygon`
+Creates a new polygon geometry from a list of lists of :py:class:`QgsPointXY`.
+
+The first list of :py:class:`QgsPointXY` objects specifies the exterior ring of the polygon, and the remaining
+lists specify any interior rings.
+
+Example
+-------
+
+.. code-block:: python
+
+       # Create a polygon geometry with a single exterior ring (a triangle)
+       polygon = QgsGeometry.fromPolygonXY([[QgsPointXY(1, 2), QgsPointXY(5, 2), QgsPointXY(5, 10), QgsPointXY(1, 2)]]))
+
+       # Create a donut shaped polygon geometry with an interior ring
+       polygon = QgsGeometry.fromPolygonXY([[QgsPointXY(1, 2), QgsPointXY(5, 2), QgsPointXY(5, 10), QgsPointXY(1, 10), QgsPointXY(1, 2)],
+                                            [QgsPointXY(3, 4), QgsPointXY(4, 4), QgsPointXY(4, 6), QgsPointXY(3, 6), QgsPointXY(3, 4)]])
 %End
+
     static QgsGeometry fromMultiPolygonXY( const QgsMultiPolygonXY &multipoly );
 %Docstring
-Creates a new geometry from a :py:class:`QgsMultiPolygon`
+Creates a new geometry from a :py:class:`QgsMultiPolygonXY`.
 %End
+
     static QgsGeometry fromRect( const QgsRectangle &rect ) /HoldGIL/;
 %Docstring
 Creates a new geometry from a :py:class:`QgsRectangle`

diff --git a/src/core/geometry/qgsgeometry.h b/src/core/geometry/qgsgeometry.h
@@ -237,12 +237,43 @@ class CORE_EXPORT QgsGeometry
      */
     static QgsGeometry fromPolyline( const QgsPolyline &polyline );
 
-    //! Creates a new geometry from a QgsMultiPolylineXY object
+    /**
+     * Creates a new geometry from a QgsMultiPolylineXY object.
+     */
     static QgsGeometry fromMultiPolylineXY( const QgsMultiPolylineXY &multiline );
-    //! Creates a new geometry from a QgsPolygon
+
+#ifndef SIP_RUN
+
+    /**
+     * Creates a new geometry from a QgsPolygonXY.
+     */
+#else
+
+    /**
+     * Creates a new polygon geometry from a list of lists of QgsPointXY.
+     *
+     * The first list of QgsPointXY objects specifies the exterior ring of the polygon, and the remaining
+     * lists specify any interior rings.
+     *
+     * ### Example
+     *
+     * \code{.py}
+     *   # Create a polygon geometry with a single exterior ring (a triangle)
+     *   polygon = QgsGeometry.fromPolygonXY([[QgsPointXY(1, 2), QgsPointXY(5, 2), QgsPointXY(5, 10), QgsPointXY(1, 2)]]))
+     *
+     *   # Create a donut shaped polygon geometry with an interior ring
+     *   polygon = QgsGeometry.fromPolygonXY([[QgsPointXY(1, 2), QgsPointXY(5, 2), QgsPointXY(5, 10), QgsPointXY(1, 10), QgsPointXY(1, 2)],
+     *                                        [QgsPointXY(3, 4), QgsPointXY(4, 4), QgsPointXY(4, 6), QgsPointXY(3, 6), QgsPointXY(3, 4)]])
+     * \endcode
+     */
+#endif
     static QgsGeometry fromPolygonXY( const QgsPolygonXY &polygon );
-    //! Creates a new geometry from a QgsMultiPolygon
+
+    /**
+     * Creates a new geometry from a QgsMultiPolygonXY.
+     */
     static QgsGeometry fromMultiPolygonXY( const QgsMultiPolygonXY &multipoly );
+
     //! Creates a new geometry from a QgsRectangle
     static QgsGeometry fromRect( const QgsRectangle &rect ) SIP_HOLDGIL;
     //! Creates a new multipart geometry from a list of QgsGeometry objects