diff --git a/docs/api_reference_dynamic.html b/docs/api_reference_dynamic.html index 8290ebc..faa33e5 100644 --- a/docs/api_reference_dynamic.html +++ b/docs/api_reference_dynamic.html @@ -108,7 +108,7 @@

McRogueFace API Reference

-

Generated on 2025-10-30 12:33:46

+

Generated on 2025-10-30 16:58:07

This documentation was dynamically generated from the compiled module.

@@ -464,17 +464,38 @@ Note:

Methods:

-
from_hexCreate Color from hex string (e.g., '#FF0000' or 'FF0000')
+
from_hexfrom_hex(hex_string: str) -> Color
+

Create a Color from a hexadecimal string. + + +Note:

+
+
hex_string: Hex color string (e.g., '#FF0000', 'FF0000', '#AABBCCDD' for RGBA)
+
+

Returns: 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')

-
lerp(...)
-

Linearly interpolate between this color and another

+
lerplerp(other: Color, t: float) -> Color
+

Linearly interpolate between this color and another. + + +Note:

+
+
other: The target Color to interpolate towards
+
t: Interpolation factor (0.0 = this color, 1.0 = other color). Automatically clamped to [0.0, 1.0]
+
+

Returns: Color: New Color representing the interpolated value All components (r, g, b, a) are interpolated independently

-
to_hex(...)
-

Convert Color to hex string

+
to_hexto_hex() -> str
+

Convert this Color to a hexadecimal string. + + + +Note:

+

Returns: str: Hex string in format '#RRGGBB' or '#RRGGBBAA' (if alpha < 255) Alpha component is only included if not fully opaque (< 255)

@@ -1048,25 +1069,41 @@ Example:
cancelcancel() -> None

Cancel the timer and remove it from the timer system. -The timer will no longer fire and cannot be restarted.

+ + + +Note:

+

Returns: None The timer will no longer fire and cannot be restarted. The callback will not be called again.

pausepause() -> None

Pause the timer, preserving the time remaining until next trigger. -The timer can be resumed later with resume().

+ + + +Note:

+

Returns: None The timer can be resumed later with resume(). Time spent paused does not count toward the interval.

restartrestart() -> None

Restart the timer from the beginning. -Resets the timer to fire after a full interval from now.

+ + + +Note:

+

Returns: None Resets the timer to fire after a full interval from now, regardless of remaining time.

resumeresume() -> None

Resume a paused timer from where it left off. -Has no effect if the timer is not paused.

+ + + +Note:

+

Returns: None Has no effect if the timer is not paused. Timer will fire after the remaining time elapses.

diff --git a/src/PyColor.cpp b/src/PyColor.cpp index e1a0b1a..4fd2154 100644 --- a/src/PyColor.cpp +++ b/src/PyColor.cpp @@ -2,21 +2,50 @@ #include "McRFPy_API.h" #include "PyObjectUtils.h" #include "PyRAII.h" +#include "McRFPy_Doc.h" #include #include 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} }; diff --git a/src/PyFont.cpp b/src/PyFont.cpp index 157656e..22ba217 100644 --- a/src/PyFont.cpp +++ b/src/PyFont.cpp @@ -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 }; diff --git a/src/PyTexture.cpp b/src/PyTexture.cpp index 631d8af..1681d37 100644 --- a/src/PyTexture.cpp +++ b/src/PyTexture.cpp @@ -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 }; diff --git a/src/PyTimer.cpp b/src/PyTimer.cpp index d1e89ec..95f619a 100644 --- a/src/PyTimer.cpp +++ b/src/PyTimer.cpp @@ -3,6 +3,7 @@ #include "GameEngine.h" #include "Resources.h" #include "PythonObjectCache.h" +#include "McRFPy_Doc.h" #include 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} }; \ No newline at end of file