docs: Phase 3 - Convert 19 module functions to MCRF_FUNCTION macros
Converted all module-level functions in McRFPy_API.cpp to use the MCRF_* documentation macro system: Audio functions (7): - createSoundBuffer, loadMusic, setMusicVolume, setSoundVolume - playSound, getMusicVolume, getSoundVolume Scene functions (5): - sceneUI, currentScene, setScene, createScene, keypressScene Timer functions (2): - setTimer, delTimer Utility functions (5): - exit, setScale, find, findAll, getMetrics Each function now uses: - MCRF_SIG for signatures - MCRF_DESC for descriptions - MCRF_ARG for parameters - MCRF_RETURNS for return values - MCRF_RAISES for exceptions - MCRF_NOTE for additional details Phase 4 assessment: PyCallable.cpp and PythonObjectCache.cpp contain only internal C++ implementation with no Python API to document. All conversions tested and verified with test_phase3_docs.py. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
29aa6e62be
commit
621d719c25
|
|
@ -1,6 +1,7 @@
|
||||||
#include "McRFPy_API.h"
|
#include "McRFPy_API.h"
|
||||||
#include "McRFPy_Automation.h"
|
#include "McRFPy_Automation.h"
|
||||||
#include "McRFPy_Libtcod.h"
|
#include "McRFPy_Libtcod.h"
|
||||||
|
#include "McRFPy_Doc.h"
|
||||||
#include "platform.h"
|
#include "platform.h"
|
||||||
#include "PyAnimation.h"
|
#include "PyAnimation.h"
|
||||||
#include "PyDrawable.h"
|
#include "PyDrawable.h"
|
||||||
|
|
@ -27,160 +28,173 @@ PyObject* McRFPy_API::mcrf_module;
|
||||||
static PyMethodDef mcrfpyMethods[] = {
|
static PyMethodDef mcrfpyMethods[] = {
|
||||||
|
|
||||||
{"createSoundBuffer", McRFPy_API::_createSoundBuffer, METH_VARARGS,
|
{"createSoundBuffer", McRFPy_API::_createSoundBuffer, METH_VARARGS,
|
||||||
"createSoundBuffer(filename: str) -> int\n\n"
|
MCRF_FUNCTION(createSoundBuffer,
|
||||||
"Load a sound effect from a file and return its buffer ID.\n\n"
|
MCRF_SIG("(filename: str)", "int"),
|
||||||
"Args:\n"
|
MCRF_DESC("Load a sound effect from a file and return its buffer ID."),
|
||||||
" filename: Path to the sound file (WAV, OGG, FLAC)\n\n"
|
MCRF_ARGS_START
|
||||||
"Returns:\n"
|
MCRF_ARG("filename", "Path to the sound file (WAV, OGG, FLAC)")
|
||||||
" int: Buffer ID for use with playSound()\n\n"
|
MCRF_RETURNS("int: Buffer ID for use with playSound()")
|
||||||
"Raises:\n"
|
MCRF_RAISES("RuntimeError", "If the file cannot be loaded")
|
||||||
" RuntimeError: If the file cannot be loaded"},
|
)},
|
||||||
{"loadMusic", McRFPy_API::_loadMusic, METH_VARARGS,
|
{"loadMusic", McRFPy_API::_loadMusic, METH_VARARGS,
|
||||||
"loadMusic(filename: str) -> None\n\n"
|
MCRF_FUNCTION(loadMusic,
|
||||||
"Load and immediately play background music from a file.\n\n"
|
MCRF_SIG("(filename: str)", "None"),
|
||||||
"Args:\n"
|
MCRF_DESC("Load and immediately play background music from a file."),
|
||||||
" filename: Path to the music file (WAV, OGG, FLAC)\n\n"
|
MCRF_ARGS_START
|
||||||
"Note:\n"
|
MCRF_ARG("filename", "Path to the music file (WAV, OGG, FLAC)")
|
||||||
" Only one music track can play at a time. Loading new music stops the current track."},
|
MCRF_RETURNS("None")
|
||||||
|
MCRF_NOTE("Only one music track can play at a time. Loading new music stops the current track.")
|
||||||
|
)},
|
||||||
{"setMusicVolume", McRFPy_API::_setMusicVolume, METH_VARARGS,
|
{"setMusicVolume", McRFPy_API::_setMusicVolume, METH_VARARGS,
|
||||||
"setMusicVolume(volume: int) -> None\n\n"
|
MCRF_FUNCTION(setMusicVolume,
|
||||||
"Set the global music volume.\n\n"
|
MCRF_SIG("(volume: int)", "None"),
|
||||||
"Args:\n"
|
MCRF_DESC("Set the global music volume."),
|
||||||
" volume: Volume level from 0 (silent) to 100 (full volume)"},
|
MCRF_ARGS_START
|
||||||
|
MCRF_ARG("volume", "Volume level from 0 (silent) to 100 (full volume)")
|
||||||
|
MCRF_RETURNS("None")
|
||||||
|
)},
|
||||||
{"setSoundVolume", McRFPy_API::_setSoundVolume, METH_VARARGS,
|
{"setSoundVolume", McRFPy_API::_setSoundVolume, METH_VARARGS,
|
||||||
"setSoundVolume(volume: int) -> None\n\n"
|
MCRF_FUNCTION(setSoundVolume,
|
||||||
"Set the global sound effects volume.\n\n"
|
MCRF_SIG("(volume: int)", "None"),
|
||||||
"Args:\n"
|
MCRF_DESC("Set the global sound effects volume."),
|
||||||
" volume: Volume level from 0 (silent) to 100 (full volume)"},
|
MCRF_ARGS_START
|
||||||
|
MCRF_ARG("volume", "Volume level from 0 (silent) to 100 (full volume)")
|
||||||
|
MCRF_RETURNS("None")
|
||||||
|
)},
|
||||||
{"playSound", McRFPy_API::_playSound, METH_VARARGS,
|
{"playSound", McRFPy_API::_playSound, METH_VARARGS,
|
||||||
"playSound(buffer_id: int) -> None\n\n"
|
MCRF_FUNCTION(playSound,
|
||||||
"Play a sound effect using a previously loaded buffer.\n\n"
|
MCRF_SIG("(buffer_id: int)", "None"),
|
||||||
"Args:\n"
|
MCRF_DESC("Play a sound effect using a previously loaded buffer."),
|
||||||
" buffer_id: Sound buffer ID returned by createSoundBuffer()\n\n"
|
MCRF_ARGS_START
|
||||||
"Raises:\n"
|
MCRF_ARG("buffer_id", "Sound buffer ID returned by createSoundBuffer()")
|
||||||
" RuntimeError: If the buffer ID is invalid"},
|
MCRF_RETURNS("None")
|
||||||
|
MCRF_RAISES("RuntimeError", "If the buffer ID is invalid")
|
||||||
|
)},
|
||||||
{"getMusicVolume", McRFPy_API::_getMusicVolume, METH_NOARGS,
|
{"getMusicVolume", McRFPy_API::_getMusicVolume, METH_NOARGS,
|
||||||
"getMusicVolume() -> int\n\n"
|
MCRF_FUNCTION(getMusicVolume,
|
||||||
"Get the current music volume level.\n\n"
|
MCRF_SIG("()", "int"),
|
||||||
"Returns:\n"
|
MCRF_DESC("Get the current music volume level."),
|
||||||
" int: Current volume (0-100)"},
|
MCRF_RETURNS("int: Current volume (0-100)")
|
||||||
|
)},
|
||||||
{"getSoundVolume", McRFPy_API::_getSoundVolume, METH_NOARGS,
|
{"getSoundVolume", McRFPy_API::_getSoundVolume, METH_NOARGS,
|
||||||
"getSoundVolume() -> int\n\n"
|
MCRF_FUNCTION(getSoundVolume,
|
||||||
"Get the current sound effects volume level.\n\n"
|
MCRF_SIG("()", "int"),
|
||||||
"Returns:\n"
|
MCRF_DESC("Get the current sound effects volume level."),
|
||||||
" int: Current volume (0-100)"},
|
MCRF_RETURNS("int: Current volume (0-100)")
|
||||||
|
)},
|
||||||
|
|
||||||
{"sceneUI", McRFPy_API::_sceneUI, METH_VARARGS,
|
{"sceneUI", McRFPy_API::_sceneUI, METH_VARARGS,
|
||||||
"sceneUI(scene: str = None) -> list\n\n"
|
MCRF_FUNCTION(sceneUI,
|
||||||
"Get all UI elements for a scene.\n\n"
|
MCRF_SIG("(scene: str = None)", "list"),
|
||||||
"Args:\n"
|
MCRF_DESC("Get all UI elements for a scene."),
|
||||||
" scene: Scene name. If None, uses current scene\n\n"
|
MCRF_ARGS_START
|
||||||
"Returns:\n"
|
MCRF_ARG("scene", "Scene name. If None, uses current scene")
|
||||||
" list: All UI elements (Frame, Caption, Sprite, Grid) in the scene\n\n"
|
MCRF_RETURNS("list: All UI elements (Frame, Caption, Sprite, Grid) in the scene")
|
||||||
"Raises:\n"
|
MCRF_RAISES("KeyError", "If the specified scene doesn't exist")
|
||||||
" KeyError: If the specified scene doesn't exist"},
|
)},
|
||||||
|
|
||||||
{"currentScene", McRFPy_API::_currentScene, METH_NOARGS,
|
{"currentScene", McRFPy_API::_currentScene, METH_NOARGS,
|
||||||
"currentScene() -> str\n\n"
|
MCRF_FUNCTION(currentScene,
|
||||||
"Get the name of the currently active scene.\n\n"
|
MCRF_SIG("()", "str"),
|
||||||
"Returns:\n"
|
MCRF_DESC("Get the name of the currently active scene."),
|
||||||
" str: Name of the current scene"},
|
MCRF_RETURNS("str: Name of the current scene")
|
||||||
|
)},
|
||||||
{"setScene", McRFPy_API::_setScene, METH_VARARGS,
|
{"setScene", McRFPy_API::_setScene, METH_VARARGS,
|
||||||
"setScene(scene: str, transition: str = None, duration: float = 0.0) -> None\n\n"
|
MCRF_FUNCTION(setScene,
|
||||||
"Switch to a different scene with optional transition effect.\n\n"
|
MCRF_SIG("(scene: str, transition: str = None, duration: float = 0.0)", "None"),
|
||||||
"Args:\n"
|
MCRF_DESC("Switch to a different scene with optional transition effect."),
|
||||||
" scene: Name of the scene to switch to\n"
|
MCRF_ARGS_START
|
||||||
" transition: Transition type ('fade', 'slide_left', 'slide_right', 'slide_up', 'slide_down')\n"
|
MCRF_ARG("scene", "Name of the scene to switch to")
|
||||||
" duration: Transition duration in seconds (default: 0.0 for instant)\n\n"
|
MCRF_ARG("transition", "Transition type ('fade', 'slide_left', 'slide_right', 'slide_up', 'slide_down')")
|
||||||
"Raises:\n"
|
MCRF_ARG("duration", "Transition duration in seconds (default: 0.0 for instant)")
|
||||||
" KeyError: If the scene doesn't exist\n"
|
MCRF_RETURNS("None")
|
||||||
" ValueError: If the transition type is invalid"},
|
MCRF_RAISES("KeyError", "If the scene doesn't exist")
|
||||||
|
MCRF_RAISES("ValueError", "If the transition type is invalid")
|
||||||
|
)},
|
||||||
{"createScene", McRFPy_API::_createScene, METH_VARARGS,
|
{"createScene", McRFPy_API::_createScene, METH_VARARGS,
|
||||||
"createScene(name: str) -> None\n\n"
|
MCRF_FUNCTION(createScene,
|
||||||
"Create a new empty scene.\n\n"
|
MCRF_SIG("(name: str)", "None"),
|
||||||
"Args:\n"
|
MCRF_DESC("Create a new empty scene."),
|
||||||
" name: Unique name for the new scene\n\n"
|
MCRF_ARGS_START
|
||||||
"Raises:\n"
|
MCRF_ARG("name", "Unique name for the new scene")
|
||||||
" ValueError: If a scene with this name already exists\n\n"
|
MCRF_RETURNS("None")
|
||||||
"Note:\n"
|
MCRF_RAISES("ValueError", "If a scene with this name already exists")
|
||||||
" The scene is created but not made active. Use setScene() to switch to it."},
|
MCRF_NOTE("The scene is created but not made active. Use setScene() to switch to it.")
|
||||||
|
)},
|
||||||
{"keypressScene", McRFPy_API::_keypressScene, METH_VARARGS,
|
{"keypressScene", McRFPy_API::_keypressScene, METH_VARARGS,
|
||||||
"keypressScene(handler: callable) -> None\n\n"
|
MCRF_FUNCTION(keypressScene,
|
||||||
"Set the keyboard event handler for the current scene.\n\n"
|
MCRF_SIG("(handler: callable)", "None"),
|
||||||
"Args:\n"
|
MCRF_DESC("Set the keyboard event handler for the current scene."),
|
||||||
" handler: Callable that receives (key_name: str, is_pressed: bool)\n\n"
|
MCRF_ARGS_START
|
||||||
"Example:\n"
|
MCRF_ARG("handler", "Callable that receives (key_name: str, is_pressed: bool)")
|
||||||
" def on_key(key, pressed):\n"
|
MCRF_RETURNS("None")
|
||||||
" if key == 'A' and pressed:\n"
|
MCRF_NOTE("Example: def on_key(key, pressed): if key == 'A' and pressed: print('A key pressed') mcrfpy.keypressScene(on_key)")
|
||||||
" print('A key pressed')\n"
|
)},
|
||||||
" mcrfpy.keypressScene(on_key)"},
|
|
||||||
|
|
||||||
{"setTimer", McRFPy_API::_setTimer, METH_VARARGS,
|
{"setTimer", McRFPy_API::_setTimer, METH_VARARGS,
|
||||||
"setTimer(name: str, handler: callable, interval: int) -> None\n\n"
|
MCRF_FUNCTION(setTimer,
|
||||||
"Create or update a recurring timer.\n\n"
|
MCRF_SIG("(name: str, handler: callable, interval: int)", "None"),
|
||||||
"Args:\n"
|
MCRF_DESC("Create or update a recurring timer."),
|
||||||
" name: Unique identifier for the timer\n"
|
MCRF_ARGS_START
|
||||||
" handler: Function called with (runtime: float) parameter\n"
|
MCRF_ARG("name", "Unique identifier for the timer")
|
||||||
" interval: Time between calls in milliseconds\n\n"
|
MCRF_ARG("handler", "Function called with (runtime: float) parameter")
|
||||||
"Note:\n"
|
MCRF_ARG("interval", "Time between calls in milliseconds")
|
||||||
" If a timer with this name exists, it will be replaced.\n"
|
MCRF_RETURNS("None")
|
||||||
" The handler receives the total runtime in seconds as its argument."},
|
MCRF_NOTE("If a timer with this name exists, it will be replaced. The handler receives the total runtime in seconds as its argument.")
|
||||||
|
)},
|
||||||
{"delTimer", McRFPy_API::_delTimer, METH_VARARGS,
|
{"delTimer", McRFPy_API::_delTimer, METH_VARARGS,
|
||||||
"delTimer(name: str) -> None\n\n"
|
MCRF_FUNCTION(delTimer,
|
||||||
"Stop and remove a timer.\n\n"
|
MCRF_SIG("(name: str)", "None"),
|
||||||
"Args:\n"
|
MCRF_DESC("Stop and remove a timer."),
|
||||||
" name: Timer identifier to remove\n\n"
|
MCRF_ARGS_START
|
||||||
"Note:\n"
|
MCRF_ARG("name", "Timer identifier to remove")
|
||||||
" No error is raised if the timer doesn't exist."},
|
MCRF_RETURNS("None")
|
||||||
|
MCRF_NOTE("No error is raised if the timer doesn't exist.")
|
||||||
|
)},
|
||||||
{"exit", McRFPy_API::_exit, METH_NOARGS,
|
{"exit", McRFPy_API::_exit, METH_NOARGS,
|
||||||
"exit() -> None\n\n"
|
MCRF_FUNCTION(exit,
|
||||||
"Cleanly shut down the game engine and exit the application.\n\n"
|
MCRF_SIG("()", "None"),
|
||||||
"Note:\n"
|
MCRF_DESC("Cleanly shut down the game engine and exit the application."),
|
||||||
" This immediately closes the window and terminates the program."},
|
MCRF_RETURNS("None")
|
||||||
|
MCRF_NOTE("This immediately closes the window and terminates the program.")
|
||||||
|
)},
|
||||||
{"setScale", McRFPy_API::_setScale, METH_VARARGS,
|
{"setScale", McRFPy_API::_setScale, METH_VARARGS,
|
||||||
"setScale(multiplier: float) -> None\n\n"
|
MCRF_FUNCTION(setScale,
|
||||||
"Scale the game window size.\n\n"
|
MCRF_SIG("(multiplier: float)", "None"),
|
||||||
"Args:\n"
|
MCRF_DESC("Scale the game window size."),
|
||||||
" multiplier: Scale factor (e.g., 2.0 for double size)\n\n"
|
MCRF_ARGS_START
|
||||||
"Note:\n"
|
MCRF_ARG("multiplier", "Scale factor (e.g., 2.0 for double size)")
|
||||||
" The internal resolution remains 1024x768, but the window is scaled.\n"
|
MCRF_RETURNS("None")
|
||||||
" This is deprecated - use Window.resolution instead."},
|
MCRF_NOTE("The internal resolution remains 1024x768, but the window is scaled. This is deprecated - use Window.resolution instead.")
|
||||||
|
)},
|
||||||
|
|
||||||
{"find", McRFPy_API::_find, METH_VARARGS,
|
{"find", McRFPy_API::_find, METH_VARARGS,
|
||||||
"find(name: str, scene: str = None) -> UIDrawable | None\n\n"
|
MCRF_FUNCTION(find,
|
||||||
"Find the first UI element with the specified name.\n\n"
|
MCRF_SIG("(name: str, scene: str = None)", "UIDrawable | None"),
|
||||||
"Args:\n"
|
MCRF_DESC("Find the first UI element with the specified name."),
|
||||||
" name: Exact name to search for\n"
|
MCRF_ARGS_START
|
||||||
" scene: Scene to search in (default: current scene)\n\n"
|
MCRF_ARG("name", "Exact name to search for")
|
||||||
"Returns:\n"
|
MCRF_ARG("scene", "Scene to search in (default: current scene)")
|
||||||
" Frame, Caption, Sprite, Grid, or Entity if found; None otherwise\n\n"
|
MCRF_RETURNS("Frame, Caption, Sprite, Grid, or Entity if found; None otherwise")
|
||||||
"Note:\n"
|
MCRF_NOTE("Searches scene UI elements and entities within grids.")
|
||||||
" Searches scene UI elements and entities within grids."},
|
)},
|
||||||
{"findAll", McRFPy_API::_findAll, METH_VARARGS,
|
{"findAll", McRFPy_API::_findAll, METH_VARARGS,
|
||||||
"findAll(pattern: str, scene: str = None) -> list\n\n"
|
MCRF_FUNCTION(findAll,
|
||||||
"Find all UI elements matching a name pattern.\n\n"
|
MCRF_SIG("(pattern: str, scene: str = None)", "list"),
|
||||||
"Args:\n"
|
MCRF_DESC("Find all UI elements matching a name pattern."),
|
||||||
" pattern: Name pattern with optional wildcards (* matches any characters)\n"
|
MCRF_ARGS_START
|
||||||
" scene: Scene to search in (default: current scene)\n\n"
|
MCRF_ARG("pattern", "Name pattern with optional wildcards (* matches any characters)")
|
||||||
"Returns:\n"
|
MCRF_ARG("scene", "Scene to search in (default: current scene)")
|
||||||
" list: All matching UI elements and entities\n\n"
|
MCRF_RETURNS("list: All matching UI elements and entities")
|
||||||
"Example:\n"
|
MCRF_NOTE("Example: findAll('enemy*') finds all elements starting with 'enemy', findAll('*_button') finds all elements ending with '_button'")
|
||||||
" findAll('enemy*') # Find all elements starting with 'enemy'\n"
|
)},
|
||||||
" findAll('*_button') # Find all elements ending with '_button'"},
|
|
||||||
|
|
||||||
{"getMetrics", McRFPy_API::_getMetrics, METH_NOARGS,
|
{"getMetrics", McRFPy_API::_getMetrics, METH_NOARGS,
|
||||||
"getMetrics() -> dict\n\n"
|
MCRF_FUNCTION(getMetrics,
|
||||||
"Get current performance metrics.\n\n"
|
MCRF_SIG("()", "dict"),
|
||||||
"Returns:\n"
|
MCRF_DESC("Get current performance metrics."),
|
||||||
" dict: Performance data with keys:\n"
|
MCRF_RETURNS("dict: Performance data with keys: frame_time (last frame duration in seconds), avg_frame_time (average frame time), fps (frames per second), draw_calls (number of draw calls), ui_elements (total UI element count), visible_elements (visible element count), current_frame (frame counter), runtime (total runtime in seconds)")
|
||||||
" - frame_time: Last frame duration in seconds\n"
|
)},
|
||||||
" - avg_frame_time: Average frame time\n"
|
|
||||||
" - fps: Frames per second\n"
|
|
||||||
" - draw_calls: Number of draw calls\n"
|
|
||||||
" - ui_elements: Total UI element count\n"
|
|
||||||
" - visible_elements: Visible element count\n"
|
|
||||||
" - current_frame: Frame counter\n"
|
|
||||||
" - runtime: Total runtime in seconds"},
|
|
||||||
|
|
||||||
{NULL, NULL, 0, NULL}
|
{NULL, NULL, 0, NULL}
|
||||||
};
|
};
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue