From 1dec6fa00fface52bf0c425f4944d7fbf8d5282d Mon Sep 17 00:00:00 2001 From: John McCardle Date: Thu, 9 Apr 2026 21:18:33 -0400 Subject: [PATCH] Improve terse docstrings on Vector, Font, Texture, GridPoint, GridPointState Replace placeholder docstrings ("SFML Vector Object", "SFML Font Object", etc.) with comprehensive constructor signatures, argument descriptions, and property listings matching the documentation standard used by other types like Color and Frame. Co-Authored-By: Claude Opus 4.6 --- src/PyFont.h | 10 +++++++++- src/PyTexture.h | 14 +++++++++++++- src/PyVector.h | 14 +++++++++++++- src/UIGridPoint.h | 20 ++++++++++++++++++-- 4 files changed, 53 insertions(+), 5 deletions(-) diff --git a/src/PyFont.h b/src/PyFont.h index f567717..1f0f3d4 100644 --- a/src/PyFont.h +++ b/src/PyFont.h @@ -38,7 +38,15 @@ namespace mcrfpydef { .tp_repr = PyFont::repr, //.tp_hash = PyFont::hash, .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("SFML Font Object"), + .tp_doc = PyDoc_STR( + "Font(filename: str)\n\n" + "A font resource for rendering text in Caption elements.\n\n" + "Args:\n" + " filename: Path to a TrueType (.ttf) or OpenType (.otf) font file.\n\n" + "Properties:\n" + " family (str, read-only): Font family name from metadata.\n" + " source (str, read-only): File path used to load this font.\n" + ), .tp_getset = PyFont::getsetters, //.tp_base = &PyBaseObject_Type, .tp_init = (initproc)PyFont::init, diff --git a/src/PyTexture.h b/src/PyTexture.h index dcadcb8..3d520df 100644 --- a/src/PyTexture.h +++ b/src/PyTexture.h @@ -68,7 +68,19 @@ namespace mcrfpydef { .tp_repr = PyTexture::repr, .tp_hash = PyTexture::hash, .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("SFML Texture Object"), + .tp_doc = PyDoc_STR( + "Texture(filename: str, sprite_width: int = 0, sprite_height: int = 0)\n\n" + "A texture atlas for sprites and tiles.\n\n" + "Args:\n" + " filename: Path to an image file (PNG, BMP, etc.).\n" + " sprite_width: Width of each sprite cell in pixels (0 = full image).\n" + " sprite_height: Height of each sprite cell in pixels (0 = full image).\n\n" + "Properties:\n" + " sprite_width, sprite_height (int, read-only): Cell dimensions.\n" + " sheet_width, sheet_height (int, read-only): Grid dimensions in cells.\n" + " sprite_count (int, read-only): Total number of sprite cells.\n" + " source (str, read-only): File path used to load this texture.\n" + ), .tp_getset = PyTexture::getsetters, //.tp_base = &PyBaseObject_Type, .tp_init = (initproc)PyTexture::init, diff --git a/src/PyVector.h b/src/PyVector.h index 300c611..c61bfc0 100644 --- a/src/PyVector.h +++ b/src/PyVector.h @@ -73,7 +73,19 @@ namespace mcrfpydef { .tp_as_sequence = &PyVector_as_sequence, .tp_hash = PyVector::hash, .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("SFML Vector Object"), + .tp_doc = PyDoc_STR( + "Vector(x: float = 0, y: float = 0)\n\n" + "2D vector for positions, sizes, and directions.\n\n" + "Args:\n" + " x: X component.\n" + " y: Y component.\n\n" + "Supports arithmetic (+, -, *, /), abs(), len() == 2,\n" + "indexing ([0] for x, [1] for y), hashing, and equality.\n\n" + "Properties:\n" + " x (float): X component.\n" + " y (float): Y component.\n" + " int (tuple[int, int], read-only): Integer floor of (x, y).\n" + ), .tp_richcompare = PyVector::richcompare, .tp_methods = PyVector::methods, .tp_getset = PyVector::getsetters, diff --git a/src/UIGridPoint.h b/src/UIGridPoint.h index 3121da1..2580cd6 100644 --- a/src/UIGridPoint.h +++ b/src/UIGridPoint.h @@ -88,7 +88,16 @@ namespace mcrfpydef { .tp_getattro = (getattrofunc)UIGridPoint::getattro, .tp_setattro = (setattrofunc)UIGridPoint::setattro, .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = "UIGridPoint object", + .tp_doc = PyDoc_STR( + "GridPoint — a single cell in a Grid.\n\n" + "Obtained via grid.at(x, y). Cannot be constructed directly.\n\n" + "Properties:\n" + " walkable (bool): Whether entities can traverse this cell.\n" + " transparent (bool): Whether this cell allows line-of-sight.\n" + " entities (list, read-only): Entities currently on this cell.\n" + " grid_pos (tuple, read-only): (x, y) position in the grid.\n\n" + "Named layer data is accessible as dynamic attributes.\n" + ), .tp_getset = UIGridPoint::getsetters, //.tp_init = (initproc)PyUIGridPoint_init, // TODO Define the init function .tp_new = NULL, // Prevent instantiation from Python - Issue #12 @@ -102,7 +111,14 @@ namespace mcrfpydef { .tp_itemsize = 0, .tp_repr = (reprfunc)UIGridPointState::repr, .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = "UIGridPointState object", // TODO: Add PyUIGridPointState tp_init + .tp_doc = PyDoc_STR( + "GridPointState — per-entity visibility state for a grid cell.\n\n" + "Obtained via entity.gridstate. Cannot be constructed directly.\n\n" + "Properties:\n" + " visible (bool): Whether this cell is currently in the entity's FOV.\n" + " discovered (bool): Whether this cell has ever been seen.\n" + " point (GridPoint, read-only): The underlying GridPoint, or None.\n" + ), .tp_getset = UIGridPointState::getsetters, .tp_new = NULL, // Prevent instantiation from Python - Issue #12 };