docs: replace all 'docstring' placeholders with comprehensive documentation (#85)

Added proper Python docstrings for all UI component classes:

UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters

UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content

UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale

UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color

All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties

This completes Phase 7 task #85 for documentation improvements.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
John McCardle 2025-07-08 09:34:22 -04:00
parent 94a0282f9f
commit d51bed623a
4 changed files with 84 additions and 4 deletions

View File

@ -65,7 +65,27 @@ namespace mcrfpydef {
//.tp_iter
//.tp_iternext
.tp_flags = Py_TPFLAGS_DEFAULT,
.tp_doc = PyDoc_STR("docstring"),
.tp_doc = PyDoc_STR("Caption(text='', x=0, y=0, font=None, fill_color=None, outline_color=None, outline=0, click=None)\n\n"
"A text display UI element with customizable font and styling.\n\n"
"Args:\n"
" text (str): The text content to display. Default: ''\n"
" x (float): X position in pixels. Default: 0\n"
" y (float): Y position in pixels. Default: 0\n"
" font (Font): Font object for text rendering. Default: engine default font\n"
" fill_color (Color): Text fill color. Default: (255, 255, 255, 255)\n"
" outline_color (Color): Text outline color. Default: (0, 0, 0, 255)\n"
" outline (float): Text outline thickness. Default: 0\n"
" click (callable): Click event handler. Default: None\n\n"
"Attributes:\n"
" text (str): The displayed text content\n"
" x, y (float): Position in pixels\n"
" font (Font): Font used for rendering\n"
" fill_color, outline_color (Color): Text appearance\n"
" outline (float): Outline thickness\n"
" click (callable): Click event handler\n"
" visible (bool): Visibility state\n"
" z_index (int): Rendering order\n"
" w, h (float): Read-only computed size based on text and font"),
.tp_methods = UICaption_methods,
//.tp_members = PyUIFrame_members,
.tp_getset = UICaption::getsetters,

View File

@ -86,7 +86,28 @@ namespace mcrfpydef {
//.tp_iter
//.tp_iternext
.tp_flags = Py_TPFLAGS_DEFAULT,
.tp_doc = PyDoc_STR("docstring"),
.tp_doc = PyDoc_STR("Frame(x=0, y=0, w=0, h=0, fill_color=None, outline_color=None, outline=0, click=None, children=None)\n\n"
"A rectangular frame UI element that can contain other drawable elements.\n\n"
"Args:\n"
" x (float): X position in pixels. Default: 0\n"
" y (float): Y position in pixels. Default: 0\n"
" w (float): Width in pixels. Default: 0\n"
" h (float): Height in pixels. Default: 0\n"
" fill_color (Color): Background fill color. Default: (0, 0, 0, 128)\n"
" outline_color (Color): Border outline color. Default: (255, 255, 255, 255)\n"
" outline (float): Border outline thickness. Default: 0\n"
" click (callable): Click event handler. Default: None\n"
" children (list): Initial list of child drawable elements. Default: None\n\n"
"Attributes:\n"
" x, y (float): Position in pixels\n"
" w, h (float): Size in pixels\n"
" fill_color, outline_color (Color): Visual appearance\n"
" outline (float): Border thickness\n"
" click (callable): Click event handler\n"
" children (list): Collection of child drawable elements\n"
" visible (bool): Visibility state\n"
" z_index (int): Rendering order\n"
" clip_children (bool): Whether to clip children to frame bounds"),
.tp_methods = UIFrame_methods,
//.tp_members = PyUIFrame_members,
.tp_getset = UIFrame::getsetters,

View File

@ -151,7 +151,29 @@ namespace mcrfpydef {
//.tp_iter
//.tp_iternext
.tp_flags = Py_TPFLAGS_DEFAULT,
.tp_doc = PyDoc_STR("docstring"),
.tp_doc = PyDoc_STR("Grid(x=0, y=0, grid_size=(20, 20), texture=None, tile_width=16, tile_height=16, scale=1.0, click=None)\n\n"
"A grid-based tilemap UI element for rendering tile-based levels and game worlds.\n\n"
"Args:\n"
" x (float): X position in pixels. Default: 0\n"
" y (float): Y position in pixels. Default: 0\n"
" grid_size (tuple): Grid dimensions as (width, height) in tiles. Default: (20, 20)\n"
" texture (Texture): Texture atlas containing tile sprites. Default: None\n"
" tile_width (int): Width of each tile in pixels. Default: 16\n"
" tile_height (int): Height of each tile in pixels. Default: 16\n"
" scale (float): Grid scaling factor. Default: 1.0\n"
" click (callable): Click event handler. Default: None\n\n"
"Attributes:\n"
" x, y (float): Position in pixels\n"
" grid_size (tuple): Grid dimensions (width, height) in tiles\n"
" tile_width, tile_height (int): Tile dimensions in pixels\n"
" texture (Texture): Tile texture atlas\n"
" scale (float): Scale multiplier\n"
" points (list): 2D array of GridPoint objects for tile data\n"
" entities (list): Collection of Entity objects in the grid\n"
" background_color (Color): Grid background color\n"
" click (callable): Click event handler\n"
" visible (bool): Visibility state\n"
" z_index (int): Rendering order"),
.tp_methods = UIGrid_all_methods,
//.tp_members = UIGrid::members,
.tp_getset = UIGrid::getsetters,

View File

@ -92,7 +92,24 @@ namespace mcrfpydef {
//.tp_iter
//.tp_iternext
.tp_flags = Py_TPFLAGS_DEFAULT,
.tp_doc = PyDoc_STR("docstring"),
.tp_doc = PyDoc_STR("Sprite(x=0, y=0, texture=None, sprite_index=0, scale=1.0, click=None)\n\n"
"A sprite UI element that displays a texture or portion of a texture atlas.\n\n"
"Args:\n"
" x (float): X position in pixels. Default: 0\n"
" y (float): Y position in pixels. Default: 0\n"
" texture (Texture): Texture object to display. Default: None\n"
" sprite_index (int): Index into texture atlas (if applicable). Default: 0\n"
" scale (float): Sprite scaling factor. Default: 1.0\n"
" click (callable): Click event handler. Default: None\n\n"
"Attributes:\n"
" x, y (float): Position in pixels\n"
" texture (Texture): The texture being displayed\n"
" sprite_index (int): Current sprite index in texture atlas\n"
" scale (float): Scale multiplier\n"
" click (callable): Click event handler\n"
" visible (bool): Visibility state\n"
" z_index (int): Rendering order\n"
" w, h (float): Read-only computed size based on texture and scale"),
.tp_methods = UISprite_methods,
//.tp_members = PyUIFrame_members,
.tp_getset = UISprite::getsetters,