Added docs (both web and in C) and refactors

docs/reST/ext/boilerplate.py

@@ -337,6 +337,7 @@ def lowercase_name(d):
         "music",
         "pygame",
         "Rect",
+        "geometry",
         "Surface",
         "sprite",
         "time",

docs/reST/index.rst

@@ -179,6 +179,9 @@ Reference
 :doc:`ref/rect`
   Flexible container for a rectangle.
 
+:doc:`ref/geometry`
+  Geometry types and operations.
+
 :doc:`ref/scrap`
   Native clipboard access.
 

docs/reST/ref/geometry.rst

@@ -0,0 +1,57 @@
+.. include:: common.txt
+
+:mod:`pygame.geometry`
+======================
+
+.. module:: pygame.geometry
+   :synopsis: pygame geometry module
+
+   | :sl:`pygame module for the Circle, Rect, and Polygon objects`
+
+.. currentmodule:: pygame
+
+.. class:: Circle
+
+   | :sl:`pygame object representing a circle`
+   | :sg:`Circle(center, radius) -> Circle`
+   | :sg:`Circle(x, y, radius) -> Circle`
+   | :sg:`Circle(object) -> Circle`
+
+   .. attribute:: x
+
+         | :sl:`center x coordinate of the circle`
+         | :sg:`x -> float`
+
+         The `x` coordinate of the center of the circle.
+
+         .. ## Circle.x ##
+
+   .. attribute:: y
+
+         | :sl:`center y coordinate of the circle`
+         | :sg:`y -> float`
+
+         The `y` coordinate of the center of the circle.
+
+         .. ## Circle.y ##
+
+   .. attribute:: r
+
+         | :sl:`radius of the circle`
+         | :sg:`r -> float`
+
+         The `r` coordinate of the center of the circle. You cannot set the radius to a negative value.
+
+         .. ## Circle.r ##
+
+   .. method:: copy
+
+         | :sl:`returns a copy of the circle`
+         | :sg:`copy() -> Circle`
+
+         The `copy` method returns a new `Circle` object having the same position and radius
+         as the original `Circle`. The function takes no arguments.
+
+         .. ## Circle.copy ##
+
+   .. ## pygame.Circle ##

docs/reST/themes/classic/elements.html

@@ -40,7 +40,7 @@ <h5>pygame-ce documentation</h5>
 We render three sets of items based on how useful to most apps.
 
 #}
-{%- set basic = ['Color', 'display', 'draw', 'event', 'font', 'image', 'key', 'locals', 'mixer', 'mouse', 'music', 'pygame', 'Rect', 'Surface', 'time'] %}
+{%- set basic = ['Color', 'display', 'draw', 'event', 'font', 'image', 'key', 'locals', 'mixer', 'mouse', 'music', 'pygame', 'Rect', 'geometry', 'Surface', 'time'] %}
 {%- set advanced = ['BufferProxy', 'freetype', 'gfxdraw', 'midi', 'PixelArray', 'pixelcopy', 'sndarray', 'surfarray', 'cursors', 'joystick', 'mask', 'math', 'sprite', 'transform'] %}
 {%- set hidden = ['Overlay', 'cdrom', 'sdl2_video', 'sdl2_controller'] %}
 {%-   if pyg_sections %}

src_c/circle.c

@@ -1,4 +1,5 @@
 #include "geometry.h"
+#include "doc/geometry_doc.h"
 
 static PyObject *
 _pg_circle_subtype_new(PyTypeObject *type, pgCircleBase *circle)
@@ -34,6 +35,7 @@ pgCircle_FromObject(PyObject *obj, pgCircleBase *out)
         return 1;
     }
 
+    /* Paths for sequences */
     if (pgSequenceFast_Check(obj)) {
         PyObject **f_arr = PySequence_Fast_ITEMS(obj);
         length = PySequence_Fast_GET_SIZE(obj);
@@ -66,7 +68,6 @@ pgCircle_FromObject(PyObject *obj, pgCircleBase *out)
         }
     }
     else if (PySequence_Check(obj)) {
-        /* Path for other sequences or Types that count as sequences*/
         PyObject *tmp = NULL;
         length = PySequence_Length(obj);
         if (length == 3) {
@@ -128,41 +129,41 @@ pgCircle_FromObject(PyObject *obj, pgCircleBase *out)
         }
     }
 
-    if (PyObject_HasAttrString(obj, "circle")) {
-        PyObject *circleattr;
-        circleattr = PyObject_GetAttrString(obj, "circle");
-        if (!circleattr) {
-            PyErr_Clear();
-            return 0;
-        }
-        if (PyCallable_Check(circleattr)) /*call if it's a method*/
-        {
-            PyObject *circleresult = PyObject_CallObject(circleattr, NULL);
-            Py_DECREF(circleattr);
-            if (!circleresult) {
-                PyErr_Clear();
-                return 0;
-            }
-            circleattr = circleresult;
-        }
-        if (!pgCircle_FromObject(circleattr, out)) {
+    /* Path for objects that have a circle attribute */
+    PyObject *circleattr;
+    if (!(circleattr = PyObject_GetAttrString(obj, "circle"))) {
+        PyErr_Clear();
+        return 0;
+    }
+
+    if (PyCallable_Check(circleattr)) /*call if it's a method*/
+    {
+        PyObject *circleresult = PyObject_CallObject(circleattr, NULL);
+        Py_DECREF(circleattr);
+        if (!circleresult) {
             PyErr_Clear();
-            Py_DECREF(circleattr);
             return 0;
         }
-        Py_DECREF(circleattr);
+        circleattr = circleresult;
+    }
 
-        return 1;
+    if (!pgCircle_FromObject(circleattr, out)) {
+        PyErr_Clear();
+        Py_DECREF(circleattr);
+        return 0;
     }
-    return 0;
+
+    Py_DECREF(circleattr);
+
+    return 1;
 }
 
 static PyObject *
 pg_circle_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
 {
     pgCircleObject *self = (pgCircleObject *)type->tp_alloc(type, 0);
 
-    if (self != NULL) {
+    if (self) {
         self->circle.x = self->circle.y = 0;
         self->circle.r = 1;
         self->weakreflist = NULL;
@@ -186,7 +187,7 @@ pg_circle_init(pgCircleObject *self, PyObject *args, PyObject *kwds)
 static void
 pg_circle_dealloc(pgCircleObject *self)
 {
-    if (self->weakreflist != NULL) {
+    if (self->weakreflist) {
         PyObject_ClearWeakRefs((PyObject *)self);
     }
 
@@ -236,8 +237,8 @@ pg_circle_str(pgCircleObject *self)
 }
 
 static struct PyMethodDef pg_circle_methods[] = {
-    {"__copy__", (PyCFunction)pg_circle_copy, METH_NOARGS, NULL},
-    {"copy", (PyCFunction)pg_circle_copy, METH_NOARGS, NULL},
+    {"__copy__", (PyCFunction)pg_circle_copy, METH_NOARGS, DOC_CIRCLE_COPY},
+    {"copy", (PyCFunction)pg_circle_copy, METH_NOARGS, DOC_CIRCLE_COPY},
     {NULL, NULL, 0, NULL}};
 
 #define GETTER_SETTER(name)                                                   \
@@ -294,9 +295,9 @@ pg_circle_setr(pgCircleObject *self, PyObject *value, void *closure)
 }
 
 static PyGetSetDef pg_circle_getsets[] = {
-    {"x", (getter)pg_circle_getx, (setter)pg_circle_setx, NULL, NULL},
-    {"y", (getter)pg_circle_gety, (setter)pg_circle_sety, NULL, NULL},
-    {"r", (getter)pg_circle_getr, (setter)pg_circle_setr, NULL, NULL},
+    {"x", (getter)pg_circle_getx, (setter)pg_circle_setx, DOC_CIRCLE_X, NULL},
+    {"y", (getter)pg_circle_gety, (setter)pg_circle_sety, DOC_CIRCLE_Y, NULL},
+    {"r", (getter)pg_circle_getr, (setter)pg_circle_setr, DOC_CIRCLE_R, NULL},
     {NULL, 0, NULL, NULL, NULL}};
 
 static PyTypeObject pgCircle_Type = {
@@ -306,7 +307,7 @@ static PyTypeObject pgCircle_Type = {
     .tp_repr = (reprfunc)pg_circle_repr,
     .tp_str = (reprfunc)pg_circle_str,
     .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
-    .tp_doc = NULL,
+    .tp_doc = DOC_CIRCLE,
     .tp_weaklistoffset = offsetof(pgCircleObject, weakreflist),
     .tp_methods = pg_circle_methods,
     .tp_getset = pg_circle_getsets,

src_c/doc/geometry_doc.h

@@ -0,0 +1,7 @@
+/* Auto generated file: with makeref.py .  Docs go in docs/reST/ref/ . */
+#define DOC_GEOMETRY "pygame module for the Circle, Rect, and Polygon objects"
+#define DOC_CIRCLE "Circle(center, radius) -> Circle\nCircle(x, y, radius) -> Circle\nCircle(object) -> Circle\npygame object representing a circle"
+#define DOC_CIRCLE_X "x -> float\ncenter x coordinate of the circle"
+#define DOC_CIRCLE_Y "y -> float\ncenter y coordinate of the circle"
+#define DOC_CIRCLE_R "r -> float\nradius of the circle"
+#define DOC_CIRCLE_COPY "copy() -> Circle\nreturns a copy of the circle"