Fully documented ctr and ctr.gfx in the C source

The documentation can be built using LDoc : run make build-doc

However, there's still a bunch of things to document.

.gitignore

@@ -1,2 +1,3 @@
 /build/*
 /ctruLua.*
+/doc/html/*

Makefile

@@ -158,6 +158,9 @@ build-all:
 	@echo Building ctruLua...
 	@make build
 
+build-doc:
+	@cd doc/ && ldoc . && cd ..
+
 #---------------------------------------------------------------------------------
 clean:
 	@rm -fr $(BUILD) $(TARGET).3dsx $(OUTPUT).smdh $(TARGET).elf
@@ -186,6 +189,9 @@ clean-all:
 	@echo Cleaning ctruLua...
 	@make clean
 
+clean-doc:
+	@rm -rf doc/html
+
 
 #---------------------------------------------------------------------------------
 else

README.md

@@ -15,6 +15,8 @@ Warning: the 'u' in the repo's name is a 'µ', not a 'u'.
 * Clone this repository and run the command `make build-all` to build all the dependencies.
 * If you only made changes to ctrµLua, run `make` to rebuild ctµLua without rebuilding all the dependencies.
 
+To build the documentation, run `make build-doc` (requires [https://github.com/stevedonovan/LDoc](LDoc)).
+
 May not work under Windows.
 
 #### Based on ctrulib by smealum: [https://github.com/smealum/ctrulib](https://github.com/smealum/ctrulib)

doc/config.ld

@@ -0,0 +1,26 @@
+-- General options
+title = "ctrµLua documentation"
+project = "ctrµLua"
+description = "ctrµLua: Lua homebrewing for 3DS"
+not_luadoc = true
+
+-- Generation options
+dir = "./html/"
+style = "!fixed"
+format = "markdown"
+plain = true
+
+-- Input files
+topics = "../README.md"
+file = "../source/"
+examples = "../sdcard/3ds/ctruLua/examples/"
+manual_url = "file://../libs/lua-5.3.1/doc/manual.html"
+
+-- Custom tags
+custom_tags = { { "newonly", hidden = true } }
+custom_display_name_handler = function(item, default_handler)
+	if item.tags.newonly then
+		return default_handler(item).." <sup><img src=../../newonly.png alt='(N3DS only)'></sup>"
+	end
+	return default_handler(item)
+end

source/ctr.c

@@ -1,3 +1,8 @@
+/***
+The `ctr` module.
+@module ctr
+@usage local ctr = require("ctr")
+*/
 #include <3ds/types.h>
 #include <3ds/services/apt.h>
 #include <3ds/os.h>
@@ -5,27 +10,84 @@
 #include <lua.h>
 #include <lauxlib.h>
 
+/***
+The `ctr.gfx` module.
+@table gfx
+@see ctr.gfx
+*/
 void load_gfx_lib(lua_State *L);
-void load_news_lib(lua_State *L);
-void load_ptm_lib(lua_State *L);
-void load_hid_lib(lua_State *L);
-void load_ir_lib(lua_State *L);
-void load_fs_lib(lua_State *L);
-void load_httpc_lib(lua_State *L);
-void load_qtm_lib(lua_State *L);
-//void load_cam_lib(lua_State *L);
-
 void unload_gfx_lib(lua_State *L);
+
+/***
+The `ctr.news` module.
+@table news
+@see ctr.news
+*/
+void load_news_lib(lua_State *L);
+
+/***
+The `ctr.ptm` module.
+@table ptm
+@see ctr.ptm
+*/
+void load_ptm_lib(lua_State *L);
+
+/***
+The `ctr.hid` module.
+@table hid
+@see ctr.hid
+*/
+void load_hid_lib(lua_State *L);
 void unload_hid_lib(lua_State *L);
+
+/***
+The `ctr.ir` module.
+@table ir
+@see ctr.ir
+*/
+void load_ir_lib(lua_State *L);
+
+/***
+The `ctr.fs` module.
+@table fs
+@see ctr.fs
+*/
+void load_fs_lib(lua_State *L);
 void unload_fs_lib(lua_State *L);
+
+/***
+The `ctr.httpc` module.
+@table httpc
+@see ctr.httpc
+*/
+void load_httpc_lib(lua_State *L);
 void unload_httpc_lib(lua_State *L);
 
+/***
+The `ctr.qtm` module.
+@table qtm
+@see ctr.qtm
+*/
+void load_qtm_lib(lua_State *L);
+
+//void load_cam_lib(lua_State *L);
+
+/***
+Return whether or not the program should continue.
+@function run
+@treturn boolean `false` if the program should exist or `true` if it can continue
+*/
 static int ctr_run(lua_State *L) {
 	lua_pushboolean(L, aptMainLoop());
 
 	return 1;
 }
 
+/***
+Return the number of milliseconds since 1st Jan 1900 00:00.
+@function time
+@treturn number milliseconds
+*/
 static int ctr_time(lua_State *L) {
 	lua_pushinteger(L, osGetTime());
 

source/gfx.c

@@ -1,3 +1,8 @@
+/***
+The `gfx` module.
+@module ctr.gfx
+@usage local gfx = require("ctr.gfx")
+*/
 #include <stdlib.h>
 
 #include <sf2d.h>
@@ -12,15 +17,43 @@
 
 bool isGfxInitialised = false;
 
+/***
+The `ctr.gfx.color` module.
+@table color
+@see ctr.gfx.color
+*/
 void load_color_lib(lua_State *L);
-void load_font_lib(lua_State *L);
-void load_texture_lib(lua_State *L);
-void load_map_lib(lua_State *L);
-
-void unload_font_lib(lua_State *L);
-
 u32 color_default;
 
+/***
+The `ctr.gfx.font` module.
+@table font
+@see ctr.gfx.font
+*/
+void load_font_lib(lua_State *L);
+void unload_font_lib(lua_State *L);
+
+/***
+The `ctr.gfx.texture` module.
+@table texture
+@see ctr.gfx.texture
+*/
+void load_texture_lib(lua_State *L);
+
+/***
+The `ctr.gfx.map` module.
+@table map
+@see ctr.gfx.map
+*/
+void load_map_lib(lua_State *L);
+
+/***
+Start drawing to a screen.
+Must be called before any draw operation.
+@function startFrame
+@tparam number screen the screen to draw to (`GFX_TOP` or `GFX_BOTTOM`)
+@tparam[opt=GFX_LEFT] number eye the eye to draw to (`GFX_LEFT` or `GFX_RIGHT`)
+*/
 static int gfx_startFrame(lua_State *L) {
 	u8 screen = luaL_checkinteger(L, 1);
 	u8 eye = luaL_optinteger(L, 2, GFX_LEFT);
@@ -30,18 +63,32 @@ static int gfx_startFrame(lua_State *L) {
 	return 0;
 }
 
+/***
+End drawing to a screen.
+Must be called after your draw operations.
+@function endFrame
+*/
 static int gfx_endFrame(lua_State *L) {
 	sf2d_end_frame();
 
 	return 0;
 }
 
+/***
+Display any drawn pixel.
+@function render
+*/
 static int gfx_render(lua_State *L) {
 	sf2d_swapbuffers();
 
 	return 0;
 }
 
+/***
+Get the current number of frame per second.
+@function getFPS
+@treturn number number of frame per seconds
+*/
 static int gfx_getFPS(lua_State *L) {
 	float fps = sf2d_get_fps();
 
@@ -50,6 +97,11 @@ static int gfx_getFPS(lua_State *L) {
 	return 1;
 }
 
+/***
+Enable or disable the stereoscopic 3D on the top screen.
+@function set3D
+@tparam boolean enable true to enable, false to disable
+*/
 static int gfx_set3D(lua_State *L) {
 	bool enable = lua_toboolean(L, 1);
 	
@@ -58,12 +110,26 @@ static int gfx_set3D(lua_State *L) {
 	return 0;
 }
 
+/***
+Get free VRAM space.
+@function vramSpaceFree
+@treturn integer free VRAM in bytes
+*/
 static int gfx_vramSpaceFree(lua_State *L) {
   lua_pushinteger(L, vramSpaceFree());
   
   return 1;
 }
 
+/***
+Draw a line on the current screen.
+@function line
+@tparam integer x1 line's starting point horizontal coordinate, in pixels
+@tparam integer y1 line's starting point vertical coordinate, in pixels
+@tparam integer x2 line's endpoint horizontal coordinate, in pixels
+@tparam integer y2 line's endpoint vertical coordinate, in pixels
+@tparam[opt=default color] integer color drawing color
+*/
 static int gfx_line(lua_State *L) {
 	int x1 = luaL_checkinteger(L, 1);
 	int y1 = luaL_checkinteger(L, 2);
@@ -77,6 +143,13 @@ static int gfx_line(lua_State *L) {
 	return 0;
 }
 
+/***
+Draw a point, a single pixel, on the current screen.
+@function point
+@tparam integer x point horizontal coordinate, in pixels
+@tparam integer y point vertical coordinate, in pixels
+@tparam[opt=default color] integer color drawing color
+*/
 static int gfx_point(lua_State *L) {
 	int x = luaL_checkinteger(L, 1);
 	int y = luaL_checkinteger(L, 2);
@@ -88,6 +161,16 @@ static int gfx_point(lua_State *L) {
 	return 0;
 }
 
+/***
+Draw a rectangle on the current screen.
+@function rectangle
+@tparam integer x rectangle origin horizontal coordinate, in pixels
+@tparam integer y rectangle origin vertical coordinate, in pixels
+@tparam integer width rectangle width, in pixels
+@tparam integer height rectangle height, in pixels
+@tparam[opt=0] number angle rectangle rotation, in radians
+@tparam[opt=default color] integer color drawing color
+*/
 static int gfx_rectangle(lua_State *L) {
 	int x = luaL_checkinteger(L, 1);
 	int y = luaL_checkinteger(L, 2);
@@ -105,6 +188,14 @@ static int gfx_rectangle(lua_State *L) {
 	return 0;
 }
 
+/***
+Draw a circle on the current screen.
+@function circle
+@tparam integer x circle center horizontal coordinate, in pixels
+@tparam integer y circle center vertical coordinate, in pixels
+@tparam integer radius circle radius, in pixels
+@tparam[opt=default color] integer color drawing color
+*/
 static int gfx_circle(lua_State *L) {
 	int x = luaL_checkinteger(L, 1);
 	int y = luaL_checkinteger(L, 2);
@@ -117,6 +208,16 @@ static int gfx_circle(lua_State *L) {
 	return 0;
 }
 
+/***
+Draw a text on the current screen.
+@function text
+@tparam integer x text drawing origin horizontal coordinate, in pixels
+@tparam integer y text drawing origin vertical coordinate, in pixels
+@tparam string text the text to draw
+@tparam[opt=9] integer size drawing size, in pixels
+@tparam[opt=default color] integer color drawing color
+@tparam[opt=default font] font font to use
+*/
 static int gfx_text(lua_State *L) {
 	int x = luaL_checkinteger(L, 1);
 	int y = luaL_checkinteger(L, 2);
@@ -161,13 +262,53 @@ static const struct luaL_Reg gfx_lib[] = {
 
 // Constants
 struct { char *name; int value; } gfx_constants[] = {
+	/***
+	Constant used to select the top screen.
+	It is equal to `0`.
+	@field GFX_TOP
+	*/
 	{ "GFX_TOP",       GFX_TOP    },
+	/***
+	Constant used to select the bottom screen.
+	It is equal to `1`.
+	@field GFX_BOTTOM
+	*/
 	{ "GFX_BOTTOM",    GFX_BOTTOM },
+	/***
+	Constant used to select the left eye.
+	It is equal to `0`.
+	@field GFX_LEFT
+	*/
 	{ "GFX_LEFT",      GFX_LEFT   },
+	/***
+	Constant used to select the right eye.
+	It is equal to `1`.
+	@field GFX_RIGHT
+	*/
 	{ "GFX_RIGHT",     GFX_RIGHT  },
+	/***
+	The top screen height, in pixels.
+	It is equal to `240`.
+	@field TOP_HEIGHT
+	*/
 	{ "TOP_HEIGHT",    240        },
+	/***
+	The top screen width, in pixels.
+	It is equal to `400`.
+	@field TOP_WIDTH
+	*/
 	{ "TOP_WIDTH",     400        },
+	/***
+	The bottom screen height, in pixels.
+	It is equal to `240`.
+	@field BOTTOM_HEIGHT
+	*/
 	{ "BOTTOM_HEIGHT", 240        },
+	/***
+	The bottom screen width, in pixels.
+	It is equal to `320`.
+	@field BOTTOM_WIDTH
+	*/
 	{ "BOTTOM_WIDTH",  320        },
 	{ NULL, 0 }
 };