docs: convert Phase 1 classes to documentation macros (Color, Font, Texture, Timer)
Converted 4 files to use MCRF_* documentation macros: - PyColor.cpp: 3 methods + 4 properties - PyFont.cpp: 2 properties (read-only) - PyTexture.cpp: 6 properties (read-only) - PyTimer.cpp: 4 methods + 7 properties All conversions verified with test_phase1_docs.py - 0 placeholders. Documentation regenerated with enhanced descriptions. Progress: 11/12 class files complete (92%) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
6aa4625b76
commit
67aba5ef1f
|
|
@ -108,7 +108,7 @@
|
|||
<body>
|
||||
<div class="container">
|
||||
<h1>McRogueFace API Reference</h1>
|
||||
<p><em>Generated on 2025-10-30 12:33:46</em></p>
|
||||
<p><em>Generated on 2025-10-30 16:58:07</em></p>
|
||||
<p><em>This documentation was dynamically generated from the compiled module.</em></p>
|
||||
|
||||
<div class="toc">
|
||||
|
|
@ -464,17 +464,38 @@ Note:</p>
|
|||
<h4>Methods:</h4>
|
||||
|
||||
<div style="margin-left: 20px; margin-bottom: 15px;">
|
||||
<h5><code class="method-name">from_hexCreate Color from hex string (e.g., '#FF0000' or 'FF0000')</code></h5>
|
||||
<h5><code class="method-name">from_hexfrom_hex(hex_string: str) -> Color</code></h5>
|
||||
<p>Create a Color from a hexadecimal string.
|
||||
|
||||
|
||||
Note:</p>
|
||||
<div style='margin-left: 20px;'>
|
||||
<div><span class='arg-name'>hex_string</span>: Hex color string (e.g., '#FF0000', 'FF0000', '#AABBCCDD' for RGBA)</div>
|
||||
</div>
|
||||
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Color: New Color object with values from hex string ValueError: If hex string is not 6 or 8 characters (RGB or RGBA) This is a class method. Call as Color.from_hex('#FF0000')</p>
|
||||
</div>
|
||||
|
||||
<div style="margin-left: 20px; margin-bottom: 15px;">
|
||||
<h5><code class="method-name">lerp(...)</code></h5>
|
||||
<p>Linearly interpolate between this color and another</p>
|
||||
<h5><code class="method-name">lerplerp(other: Color, t: float) -> Color</code></h5>
|
||||
<p>Linearly interpolate between this color and another.
|
||||
|
||||
|
||||
Note:</p>
|
||||
<div style='margin-left: 20px;'>
|
||||
<div><span class='arg-name'>other</span>: The target Color to interpolate towards</div>
|
||||
<div><span class='arg-name'>t</span>: Interpolation factor (0.0 = this color, 1.0 = other color). Automatically clamped to [0.0, 1.0]</div>
|
||||
</div>
|
||||
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Color: New Color representing the interpolated value All components (r, g, b, a) are interpolated independently</p>
|
||||
</div>
|
||||
|
||||
<div style="margin-left: 20px; margin-bottom: 15px;">
|
||||
<h5><code class="method-name">to_hex(...)</code></h5>
|
||||
<p>Convert Color to hex string</p>
|
||||
<h5><code class="method-name">to_hexto_hex() -> str</code></h5>
|
||||
<p>Convert this Color to a hexadecimal string.
|
||||
|
||||
|
||||
|
||||
Note:</p>
|
||||
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> str: Hex string in format '#RRGGBB' or '#RRGGBBAA' (if alpha < 255) Alpha component is only included if not fully opaque (< 255)</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
|
@ -1048,25 +1069,41 @@ Example:
|
|||
<div style="margin-left: 20px; margin-bottom: 15px;">
|
||||
<h5><code class="method-name">cancelcancel() -> None</code></h5>
|
||||
<p>Cancel the timer and remove it from the timer system.
|
||||
The timer will no longer fire and cannot be restarted.</p>
|
||||
|
||||
|
||||
|
||||
Note:</p>
|
||||
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None The timer will no longer fire and cannot be restarted. The callback will not be called again.</p>
|
||||
</div>
|
||||
|
||||
<div style="margin-left: 20px; margin-bottom: 15px;">
|
||||
<h5><code class="method-name">pausepause() -> None</code></h5>
|
||||
<p>Pause the timer, preserving the time remaining until next trigger.
|
||||
The timer can be resumed later with resume().</p>
|
||||
|
||||
|
||||
|
||||
Note:</p>
|
||||
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None The timer can be resumed later with resume(). Time spent paused does not count toward the interval.</p>
|
||||
</div>
|
||||
|
||||
<div style="margin-left: 20px; margin-bottom: 15px;">
|
||||
<h5><code class="method-name">restartrestart() -> None</code></h5>
|
||||
<p>Restart the timer from the beginning.
|
||||
Resets the timer to fire after a full interval from now.</p>
|
||||
|
||||
|
||||
|
||||
Note:</p>
|
||||
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None Resets the timer to fire after a full interval from now, regardless of remaining time.</p>
|
||||
</div>
|
||||
|
||||
<div style="margin-left: 20px; margin-bottom: 15px;">
|
||||
<h5><code class="method-name">resumeresume() -> None</code></h5>
|
||||
<p>Resume a paused timer from where it left off.
|
||||
Has no effect if the timer is not paused.</p>
|
||||
|
||||
|
||||
|
||||
Note:</p>
|
||||
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None Has no effect if the timer is not paused. Timer will fire after the remaining time elapses.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
|
|
|||
|
|
@ -2,21 +2,50 @@
|
|||
#include "McRFPy_API.h"
|
||||
#include "PyObjectUtils.h"
|
||||
#include "PyRAII.h"
|
||||
#include "McRFPy_Doc.h"
|
||||
#include <string>
|
||||
#include <cstdio>
|
||||
|
||||
PyGetSetDef PyColor::getsetters[] = {
|
||||
{"r", (getter)PyColor::get_member, (setter)PyColor::set_member, "Red component", (void*)0},
|
||||
{"g", (getter)PyColor::get_member, (setter)PyColor::set_member, "Green component", (void*)1},
|
||||
{"b", (getter)PyColor::get_member, (setter)PyColor::set_member, "Blue component", (void*)2},
|
||||
{"a", (getter)PyColor::get_member, (setter)PyColor::set_member, "Alpha component", (void*)3},
|
||||
{"r", (getter)PyColor::get_member, (setter)PyColor::set_member,
|
||||
MCRF_PROPERTY(r, "Red component (0-255). Automatically clamped to valid range."), (void*)0},
|
||||
{"g", (getter)PyColor::get_member, (setter)PyColor::set_member,
|
||||
MCRF_PROPERTY(g, "Green component (0-255). Automatically clamped to valid range."), (void*)1},
|
||||
{"b", (getter)PyColor::get_member, (setter)PyColor::set_member,
|
||||
MCRF_PROPERTY(b, "Blue component (0-255). Automatically clamped to valid range."), (void*)2},
|
||||
{"a", (getter)PyColor::get_member, (setter)PyColor::set_member,
|
||||
MCRF_PROPERTY(a, "Alpha component (0-255, where 0=transparent, 255=opaque). Automatically clamped to valid range."), (void*)3},
|
||||
{NULL}
|
||||
};
|
||||
|
||||
PyMethodDef PyColor::methods[] = {
|
||||
{"from_hex", (PyCFunction)PyColor::from_hex, METH_VARARGS | METH_CLASS, "Create Color from hex string (e.g., '#FF0000' or 'FF0000')"},
|
||||
{"to_hex", (PyCFunction)PyColor::to_hex, METH_NOARGS, "Convert Color to hex string"},
|
||||
{"lerp", (PyCFunction)PyColor::lerp, METH_VARARGS, "Linearly interpolate between this color and another"},
|
||||
{"from_hex", (PyCFunction)PyColor::from_hex, METH_VARARGS | METH_CLASS,
|
||||
MCRF_METHOD(Color, from_hex,
|
||||
MCRF_SIG("(hex_string: str)", "Color"),
|
||||
MCRF_DESC("Create a Color from a hexadecimal string."),
|
||||
MCRF_ARGS_START
|
||||
MCRF_ARG("hex_string", "Hex color string (e.g., '#FF0000', 'FF0000', '#AABBCCDD' for RGBA)")
|
||||
MCRF_RETURNS("Color: New Color object with values from hex string")
|
||||
MCRF_RAISES("ValueError", "If hex string is not 6 or 8 characters (RGB or RGBA)")
|
||||
MCRF_NOTE("This is a class method. Call as Color.from_hex('#FF0000')")
|
||||
)},
|
||||
{"to_hex", (PyCFunction)PyColor::to_hex, METH_NOARGS,
|
||||
MCRF_METHOD(Color, to_hex,
|
||||
MCRF_SIG("()", "str"),
|
||||
MCRF_DESC("Convert this Color to a hexadecimal string."),
|
||||
MCRF_RETURNS("str: Hex string in format '#RRGGBB' or '#RRGGBBAA' (if alpha < 255)")
|
||||
MCRF_NOTE("Alpha component is only included if not fully opaque (< 255)")
|
||||
)},
|
||||
{"lerp", (PyCFunction)PyColor::lerp, METH_VARARGS,
|
||||
MCRF_METHOD(Color, lerp,
|
||||
MCRF_SIG("(other: Color, t: float)", "Color"),
|
||||
MCRF_DESC("Linearly interpolate between this color and another."),
|
||||
MCRF_ARGS_START
|
||||
MCRF_ARG("other", "The target Color to interpolate towards")
|
||||
MCRF_ARG("t", "Interpolation factor (0.0 = this color, 1.0 = other color). Automatically clamped to [0.0, 1.0]")
|
||||
MCRF_RETURNS("Color: New Color representing the interpolated value")
|
||||
MCRF_NOTE("All components (r, g, b, a) are interpolated independently")
|
||||
)},
|
||||
{NULL}
|
||||
};
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
#include "PyFont.h"
|
||||
#include "McRFPy_API.h"
|
||||
#include "McRFPy_Doc.h"
|
||||
|
||||
|
||||
PyFont::PyFont(std::string filename)
|
||||
|
|
@ -73,7 +74,9 @@ PyObject* PyFont::get_source(PyFontObject* self, void* closure)
|
|||
}
|
||||
|
||||
PyGetSetDef PyFont::getsetters[] = {
|
||||
{"family", (getter)PyFont::get_family, NULL, "Font family name", NULL},
|
||||
{"source", (getter)PyFont::get_source, NULL, "Source filename of the font", NULL},
|
||||
{"family", (getter)PyFont::get_family, NULL,
|
||||
MCRF_PROPERTY(family, "Font family name (str, read-only). Retrieved from font metadata."), NULL},
|
||||
{"source", (getter)PyFont::get_source, NULL,
|
||||
MCRF_PROPERTY(source, "Source filename path (str, read-only). The path used to load this font."), NULL},
|
||||
{NULL} // Sentinel
|
||||
};
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
#include "PyTexture.h"
|
||||
#include "McRFPy_API.h"
|
||||
#include "McRFPy_Doc.h"
|
||||
|
||||
PyTexture::PyTexture(std::string filename, int sprite_w, int sprite_h)
|
||||
: source(filename), sprite_width(sprite_w), sprite_height(sprite_h), sheet_width(0), sheet_height(0)
|
||||
|
|
@ -131,11 +132,17 @@ PyObject* PyTexture::get_source(PyTextureObject* self, void* closure)
|
|||
}
|
||||
|
||||
PyGetSetDef PyTexture::getsetters[] = {
|
||||
{"sprite_width", (getter)PyTexture::get_sprite_width, NULL, "Width of each sprite in pixels", NULL},
|
||||
{"sprite_height", (getter)PyTexture::get_sprite_height, NULL, "Height of each sprite in pixels", NULL},
|
||||
{"sheet_width", (getter)PyTexture::get_sheet_width, NULL, "Number of sprite columns in the texture", NULL},
|
||||
{"sheet_height", (getter)PyTexture::get_sheet_height, NULL, "Number of sprite rows in the texture", NULL},
|
||||
{"sprite_count", (getter)PyTexture::get_sprite_count, NULL, "Total number of sprites in the texture", NULL},
|
||||
{"source", (getter)PyTexture::get_source, NULL, "Source filename of the texture", NULL},
|
||||
{"sprite_width", (getter)PyTexture::get_sprite_width, NULL,
|
||||
MCRF_PROPERTY(sprite_width, "Width of each sprite in pixels (int, read-only). Specified during texture initialization."), NULL},
|
||||
{"sprite_height", (getter)PyTexture::get_sprite_height, NULL,
|
||||
MCRF_PROPERTY(sprite_height, "Height of each sprite in pixels (int, read-only). Specified during texture initialization."), NULL},
|
||||
{"sheet_width", (getter)PyTexture::get_sheet_width, NULL,
|
||||
MCRF_PROPERTY(sheet_width, "Number of sprite columns in the texture sheet (int, read-only). Calculated as texture_width / sprite_width."), NULL},
|
||||
{"sheet_height", (getter)PyTexture::get_sheet_height, NULL,
|
||||
MCRF_PROPERTY(sheet_height, "Number of sprite rows in the texture sheet (int, read-only). Calculated as texture_height / sprite_height."), NULL},
|
||||
{"sprite_count", (getter)PyTexture::get_sprite_count, NULL,
|
||||
MCRF_PROPERTY(sprite_count, "Total number of sprites in the texture sheet (int, read-only). Equals sheet_width * sheet_height."), NULL},
|
||||
{"source", (getter)PyTexture::get_source, NULL,
|
||||
MCRF_PROPERTY(source, "Source filename path (str, read-only). The path used to load this texture."), NULL},
|
||||
{NULL} // Sentinel
|
||||
};
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@
|
|||
#include "GameEngine.h"
|
||||
#include "Resources.h"
|
||||
#include "PythonObjectCache.h"
|
||||
#include "McRFPy_Doc.h"
|
||||
#include <sstream>
|
||||
|
||||
PyObject* PyTimer::repr(PyObject* self) {
|
||||
|
|
@ -307,38 +308,50 @@ PyObject* PyTimer::get_name(PyTimerObject* self, void* closure) {
|
|||
|
||||
PyGetSetDef PyTimer::getsetters[] = {
|
||||
{"name", (getter)PyTimer::get_name, NULL,
|
||||
"Timer name (read-only)", NULL},
|
||||
MCRF_PROPERTY(name, "Timer name (str, read-only). Unique identifier for this timer."), NULL},
|
||||
{"interval", (getter)PyTimer::get_interval, (setter)PyTimer::set_interval,
|
||||
"Timer interval in milliseconds", NULL},
|
||||
MCRF_PROPERTY(interval, "Timer interval in milliseconds (int). Must be positive. Can be changed while timer is running."), NULL},
|
||||
{"remaining", (getter)PyTimer::get_remaining, NULL,
|
||||
"Time remaining until next trigger in milliseconds", NULL},
|
||||
MCRF_PROPERTY(remaining, "Time remaining until next trigger in milliseconds (int, read-only). Preserved when timer is paused."), NULL},
|
||||
{"paused", (getter)PyTimer::get_paused, NULL,
|
||||
"Whether the timer is paused", NULL},
|
||||
MCRF_PROPERTY(paused, "Whether the timer is paused (bool, read-only). Paused timers preserve their remaining time."), NULL},
|
||||
{"active", (getter)PyTimer::get_active, NULL,
|
||||
"Whether the timer is active and not paused", NULL},
|
||||
MCRF_PROPERTY(active, "Whether the timer is active and not paused (bool, read-only). False if cancelled or paused."), NULL},
|
||||
{"callback", (getter)PyTimer::get_callback, (setter)PyTimer::set_callback,
|
||||
"The callback function to be called", NULL},
|
||||
MCRF_PROPERTY(callback, "The callback function to be called when timer fires (callable). Can be changed while timer is running."), NULL},
|
||||
{"once", (getter)PyTimer::get_once, (setter)PyTimer::set_once,
|
||||
"Whether the timer stops after firing once", NULL},
|
||||
MCRF_PROPERTY(once, "Whether the timer stops after firing once (bool). If False, timer repeats indefinitely."), NULL},
|
||||
{NULL}
|
||||
};
|
||||
|
||||
PyMethodDef PyTimer::methods[] = {
|
||||
{"pause", (PyCFunction)PyTimer::pause, METH_NOARGS,
|
||||
"pause() -> None\n\n"
|
||||
"Pause the timer, preserving the time remaining until next trigger.\n"
|
||||
"The timer can be resumed later with resume()."},
|
||||
MCRF_METHOD(Timer, pause,
|
||||
MCRF_SIG("()", "None"),
|
||||
MCRF_DESC("Pause the timer, preserving the time remaining until next trigger."),
|
||||
MCRF_RETURNS("None")
|
||||
MCRF_NOTE("The timer can be resumed later with resume(). Time spent paused does not count toward the interval.")
|
||||
)},
|
||||
{"resume", (PyCFunction)PyTimer::resume, METH_NOARGS,
|
||||
"resume() -> None\n\n"
|
||||
"Resume a paused timer from where it left off.\n"
|
||||
"Has no effect if the timer is not paused."},
|
||||
MCRF_METHOD(Timer, resume,
|
||||
MCRF_SIG("()", "None"),
|
||||
MCRF_DESC("Resume a paused timer from where it left off."),
|
||||
MCRF_RETURNS("None")
|
||||
MCRF_NOTE("Has no effect if the timer is not paused. Timer will fire after the remaining time elapses.")
|
||||
)},
|
||||
{"cancel", (PyCFunction)PyTimer::cancel, METH_NOARGS,
|
||||
"cancel() -> None\n\n"
|
||||
"Cancel the timer and remove it from the timer system.\n"
|
||||
"The timer will no longer fire and cannot be restarted."},
|
||||
MCRF_METHOD(Timer, cancel,
|
||||
MCRF_SIG("()", "None"),
|
||||
MCRF_DESC("Cancel the timer and remove it from the timer system."),
|
||||
MCRF_RETURNS("None")
|
||||
MCRF_NOTE("The timer will no longer fire and cannot be restarted. The callback will not be called again.")
|
||||
)},
|
||||
{"restart", (PyCFunction)PyTimer::restart, METH_NOARGS,
|
||||
"restart() -> None\n\n"
|
||||
"Restart the timer from the beginning.\n"
|
||||
"Resets the timer to fire after a full interval from now."},
|
||||
MCRF_METHOD(Timer, restart,
|
||||
MCRF_SIG("()", "None"),
|
||||
MCRF_DESC("Restart the timer from the beginning."),
|
||||
MCRF_RETURNS("None")
|
||||
MCRF_NOTE("Resets the timer to fire after a full interval from now, regardless of remaining time.")
|
||||
)},
|
||||
{NULL}
|
||||
};
|
||||
Loading…
Reference in New Issue