Platform specific API documentation generation.

1 files changed, 94 insertions, 22 deletions

diff --git a/src/platforms/core_desktop.c b/src/platforms/core_desktop.c
index 4ea871a..614062d 100644
--- a/src/platforms/core_desktop.c
+++ b/src/platforms/core_desktop.c
@@ -7,22 +7,22 @@ static void platformDefineGlobals() {
 	lua_State *L = state->luaState;
 
 	lua_getglobal( L, "RL" );
-
-		/* KeyboardKey */
+/*DOC_DEFINES_START*/
+	/* Keyboard keys (US keyboard layout) */
 	assignGlobalInt( GLFW_KEY_UNKNOWN, "GLFW_KEY_UNKNOWN" ); // Key: Unknown
-		/* GLFW API tokens. */
+	/* GLFW API tokens. */
 	assignGlobalInt( GLFW_RELEASE, "GLFW_RELEASE" ); // The key or mouse button was released
 	assignGlobalInt( GLFW_PRESS, "GLFW_PRESS" ); // The key or mouse button was pressed
 	assignGlobalInt( GLFW_REPEAT, "GLFW_REPEAT" ); // The key was held down until it repeated
 	assignGlobalInt( GLFW_CONNECTED, "GLFW_CONNECTED" ); // Joystick connected
 	assignGlobalInt( GLFW_DISCONNECTED, "GLFW_DISCONNECTED" ); // Joystick disconnected
-		/* Window Events. */
+	/* GLFW Window Events. */
 	assignGlobalInt( GLFW_WINDOW_SIZE_EVENT, "GLFW_WINDOW_SIZE_EVENT" ); // GLFW event window size changed
 	assignGlobalInt( GLFW_WINDOW_MAXIMIZE_EVENT, "GLFW_WINDOW_MAXIMIZE_EVENT" ); // GLFW event window maximize
 	assignGlobalInt( GLFW_WINDOW_ICONYFY_EVENT, "GLFW_WINDOW_ICONYFY_EVENT" ); // GLFW event window iconify
 	assignGlobalInt( GLFW_WINDOW_FOCUS_EVENT, "GLFW_WINDOW_FOCUS_EVENT" ); // GLFW event window focus
 	assignGlobalInt( GLFW_WINDOW_DROP_EVENT, "GLFW_WINDOW_DROP_EVENT" ); // GLFW event window drop
-	/* Input Events. */
+	/* GLFW Input Events. */
 	assignGlobalInt( GLFW_KEY_EVENT, "GLFW_KEY_EVENT" ); // GLFW event keyboard key
 	assignGlobalInt( GLFW_CHAR_EVENT, "GLFW_CHAR_EVENT" ); // GLFW event Unicode character
 	assignGlobalInt( GLFW_MOUSE_BUTTON_EVENT, "GLFW_MOUSE_BUTTON_EVENT" ); // GLFW event mouse button
@@ -30,31 +30,24 @@ static void platformDefineGlobals() {
 	assignGlobalInt( GLFW_MOUSE_SCROLL_EVENT, "GLFW_MOUSE_SCROLL_EVENT" ); // GLFW event mouse scroll
 	assignGlobalInt( GLFW_CURSOR_ENTER_EVENT, "GLFW_CURSOR_ENTER_EVENT" ); // GLFW event cursor enter/leave
 	assignGlobalInt( GLFW_JOYSTICK_EVENT, "GLFW_JOYSTICK_EVENT" ); // GLFW event joystick
-	/* Pen Tablet Events. NOTE! Experimental. Needs glfw PR https://github.com/glfw/glfw/pull/1445. */
+	/* GLFW Pen Tablet Events. NOTE! Experimental. Needs glfw PR https://github.com/glfw/glfw/pull/1445. */
 	// assignGlobalInt( GLFW_PEN_TABLET_DATA_EVENT, "GLFW_PEN_TABLET_DATA_EVENT" ); // GLFW event pen tablet data
 	// assignGlobalInt( GLFW_PEN_TABLET_CURSOR_EVENT, "GLFW_PEN_TABLET_CURSOR_EVENT" ); // GLFW event pen tablet cursor
 	// assignGlobalInt( GLFW_PEN_TABLET_PROXIMITY_EVENT, "GLFW_PEN_TABLET_PROXIMITY_EVENT" ); // GLFW event pen tablet proximity
-
+/*DOC_DEFINES_END*/
 	lua_pop( L, -1 );
 }
 
 /* Functions. */
 
 /*
-## Core - Input-related functions: keyboard.
+## GLFW Core - Input-related functions: keyboard
 */
 
 /*
 > keyName = RL.GetKeyName( int key, int scancode )
 
 This function returns the name of the specified printable key, encoded as UTF-8.
-This is typically the character that key would produce without any modifier keys,
-intended for displaying key bindings to the user. For dead keys, it is typically
-the diacritic it would add to a character.
-
-Do not use this function for text input. You will break text input for many
-languages even if it happens to work for yours.
-
 If the key is KEY_UNKNOWN, the scancode is used to identify the key,
 otherwise the scancode is ignored. If you specify a non-printable key,
 or KEY_UNKNOWN and a scancode that maps to a non-printable key,
@@ -107,8 +100,15 @@ static void luaPlatformRegister() {
 
 /* Events. */
 
-/* Window events. */
+/*
+## Window events
+*/
+
+/*
+> GLFWwindowsizeEvent = { int type, int width, int height }
 
+Called when the window is resized. Type GLFW_WINDOW_SIZE_EVENT
+*/
 static void windowSizeEvent( GLFWwindow *window, int width, int height ) {
 	/* Pass through to raylib callback. */
 	state->raylibWindowSizeCallback( window, width, height );
@@ -140,6 +140,11 @@ static void windowSizeEvent( GLFWwindow *window, int width, int height ) {
 
 #if !defined( PLATFORM_WEB )
 
+/*
+> GLFWwindowmaximizeEvent = { int type, int maximized }
+
+Called when the window is maximized or restored. Type GLFW_WINDOW_MAXIMIZE_EVENT
+*/
 static void windowMaximizeEvent( GLFWwindow *window, int maximized ) {
 	/* Pass through to raylib callback. */
 	state->raylibWindowMaximizeCallback( window, maximized );
@@ -169,6 +174,11 @@ static void windowMaximizeEvent( GLFWwindow *window, int maximized ) {
 
 #endif
 
+/*
+> GLFWwindowiconifyEvent = { int type, int iconified }
+
+Called when the window is iconified or restored. Type GLFW_WINDOW_ICONYFY_EVENT
+*/
 static void windowIconyfyEvent( GLFWwindow *window, int iconified ) {
 	/* Pass through to raylib callback. */
 	state->raylibWindowIconifyCallback( window, iconified );
@@ -196,6 +206,11 @@ static void windowIconyfyEvent( GLFWwindow *window, int iconified ) {
 	lua_pop( L, -1 );
 }
 
+/*
+> GLFWwindowfocusEvent = { int type, int focused }
+
+Called when the window gains or loses input focus. Type GLFW_WINDOW_FOCUS_EVENT
+*/
 static void windowFocusEvent( GLFWwindow *window, int focused ) {
 	/* Pass through to raylib callback. */
 	state->raylibWindowFocusCallback( window, focused );
@@ -223,6 +238,11 @@ static void windowFocusEvent( GLFWwindow *window, int focused ) {
 	lua_pop( L, -1 );
 }
 
+/*
+> GLFWdropEvent = { int type, int count, string{} paths }
+
+Called when files are dropped to the window. Type GLFW_WINDOW_DROP_EVENT
+*/
 static void windowDropEvent( GLFWwindow *window, int count, const char **paths ) {
 	/* Pass through to raylib callback. */
 	state->raylibWindowDropCallback( window, count, paths );
@@ -258,8 +278,15 @@ static void windowDropEvent( GLFWwindow *window, int count, const char **paths )
 	lua_pop( L, -1 );
 }
 
-/* Input events. */
+/*
+## Input events
+*/
+
+/*
+> GLFWkeyEvent = { int type, int key, int scancode, int action, int mods }
 
+Called when a physical key is pressed or released or when it repeats. Type GLFW_KEY_EVENT
+*/
 static void keyInputEvent( GLFWwindow* window, int key, int scancode, int action, int mods ) {
 	/* Pass through to raylib callback. */
 	state->raylibKeyCallback( window, key, scancode, action, mods );
@@ -293,6 +320,11 @@ static void keyInputEvent( GLFWwindow* window, int key, int scancode, int action
 	lua_pop( L, -1 );
 }
 
+/*
+> GLFWcharEvent = { int type, int key }
+
+Unicode code points for key events that would have led to regular text input and generally behaves as a standard text field on that platform. Type GLFW_CHAR_EVENT
+*/
 static void charInputEvent( GLFWwindow* window, unsigned int key ) {
 	/* Pass through to raylib callback. */
 	state->raylibCharCallback( window, key );
@@ -320,6 +352,11 @@ static void charInputEvent( GLFWwindow* window, unsigned int key ) {
 	lua_pop( L, -1 );
 }
 
+/*
+> GLFWmousebuttonEvent = { int type, int button, int action, int mods }
+
+Called when a mouse button is pressed or released. Type GLFW_MOUSE_BUTTON_EVENT
+*/
 static void mouseButtonInputEvent( GLFWwindow* window, int button, int action, int mods ) {
 	/* Pass through to raylib callback. */
 	state->raylibMouseButtonCallback( window, button, action, mods );
@@ -351,6 +388,11 @@ static void mouseButtonInputEvent( GLFWwindow* window, int button, int action, i
 	lua_pop( L, -1 );
 }
 
+/*
+> GLFWcursorposEvent = { int type, float x, float y }
+
+Called when the cursor moves over the window. Type GLFW_MOUSE_CURSOR_POS_EVENT
+*/
 static void mouseCursorPosInputEvent( GLFWwindow* window, double x, double y ) {
 	/* Pass through to raylib callback. */
 	state->raylibMouseCursorPosCallback( window, x, y );
@@ -380,6 +422,11 @@ static void mouseCursorPosInputEvent( GLFWwindow* window, double x, double y ) {
 	lua_pop( L, -1 );
 }
 
+/*
+> GLFWscrollEvent = { int type, float xoffset, float yoffset }
+
+Called when the user scrolls, whether with a mouse wheel or touchpad gesture. Type GLFW_MOUSE_SCROLL_EVENT
+*/
 static void mouseScrollInputEvent( GLFWwindow* window, double xoffset, double yoffset ) {
 	/* Pass through to raylib callback. */
 	state->raylibMouseScrollCallback( window, xoffset, yoffset );
@@ -409,6 +456,11 @@ static void mouseScrollInputEvent( GLFWwindow* window, double xoffset, double yo
 	lua_pop( L, -1 );
 }
 
+/*
+> GLFWcursorenterEvent = { int type, int enter }
+
+Called when the cursor enters or leaves the content area of a window. Type GLFW_CURSOR_ENTER_EVENT
+*/
 static void cursorEnterInputEvent( GLFWwindow* window, int enter ) {
 	/* Pass through to raylib callback. */
 	state->raylibCursorEnterCallback( window, enter );
@@ -436,7 +488,12 @@ static void cursorEnterInputEvent( GLFWwindow* window, int enter ) {
 	lua_pop( L, -1 );
 }
 
-static void joystickInputEvent( int jid, int event ) {
+/*
+> GLFWjoystickEvent = { int type, int jid, int event }
+
+Called when a joystick is connected or disconnected. Type GLFW_JOYSTICK_EVENT
+*/
+static void joystickEvent( int jid, int event ) {
 	/* Pass through to raylib callback. */
 	if ( state->raylibJoystickCallback != NULL ) {
 		state->raylibJoystickCallback( jid, event );
@@ -467,7 +524,12 @@ static void joystickInputEvent( int jid, int event ) {
 	lua_pop( L, -1 );
 }
 
-// /* NOTE! Experimental. Needs glfw PR https://github.com/glfw/glfw/pull/1445 */
+/*
+> GLFWpentabletdataEvent = { int type, float x, float y, float z, float pressure, float pitch, float yaw, float roll }
+
+Called when the pen tablet data is updated. Type GLFW_PEN_TABLET_DATA_EVENT
+NOTE! Experimental. Needs glfw PR https://github.com/glfw/glfw/pull/1445
+*/
 // static void penTabletDataEvent( double x, double y, double z, double pressure, double pitch, double yaw, double roll ) {
 // 	lua_State *L = state->luaState;
 
@@ -504,7 +566,12 @@ static void joystickInputEvent( int jid, int event ) {
 // 	lua_pop( L, -1 );
 // }
 
-// /* NOTE! Experimental. Needs glfw PR https://github.com/glfw/glfw/pull/1445 */
+/*
+> GLFWpentabletcursorEvent = { int type, int identifier }
+
+Called when the pen tablet cursor has changed. Type GLFW_PEN_TABLET_CURSOR_EVENT
+NOTE! Experimental. Needs glfw PR https://github.com/glfw/glfw/pull/1445
+*/
 // static void penTabletCursorEvent( unsigned int identifier ) {
 // 	lua_State *L = state->luaState;
 
@@ -529,7 +596,12 @@ static void joystickInputEvent( int jid, int event ) {
 // 	lua_pop( L, -1 );
 // }
 
-// /* NOTE! Experimental. Needs glfw PR https://github.com/glfw/glfw/pull/1445 */
+/*
+> GLFWpentabletproximityEvent = { int type, int proxState }
+
+Called when the pen tablet proximity has changed. Type GLFW_PEN_TABLET_PROXIMITY_EVENT
+NOTE! Experimental. Needs glfw PR https://github.com/glfw/glfw/pull/1445
+*/
 // static void penTabletProximityEvent( int proxState ) {
 // 	lua_State *L = state->luaState;
 
@@ -571,7 +643,7 @@ static void platformRegisterEvents() {
 	state->raylibMouseCursorPosCallback = glfwSetCursorPosCallback( GetWindowHandle(), mouseCursorPosInputEvent );
 	state->raylibMouseScrollCallback = glfwSetScrollCallback( GetWindowHandle(), mouseScrollInputEvent );
 	state->raylibCursorEnterCallback = glfwSetCursorEnterCallback( GetWindowHandle(), cursorEnterInputEvent );
-	state->raylibJoystickCallback = glfwSetJoystickCallback( joystickInputEvent );
+	state->raylibJoystickCallback = glfwSetJoystickCallback( joystickEvent );
 	/* NOTE! Experimental. Needs glfw PR https://github.com/glfw/glfw/pull/1445 */
 	// state->glfwtabletDataCallback = glfwSetPenTabletDataCallback( penTabletDataEvent );
 	// state->glfwtabletCursorCallback = glfwSetPenTabletCursorCallback( penTabletCursorEvent );