diff --git a/API.md b/API.md
new file mode 100644
index 0000000..2828629
--- /dev/null
+++ b/API.md
@@ -0,0 +1,6 @@
+Lua API reference
+=================
+
+We actively support LuaJIT and Lua 5.4. Lua 5.1, 5.2 and 5.3 *should* work but I don't always test against them.
+
+TODO see anselme.lua, it is reasonably commentated and we should probably generate some documentation using LDoc.
diff --git a/REFERENCE.md b/LANGUAGE.md
similarity index 99%
rename from REFERENCE.md
rename to LANGUAGE.md
index 726bd7c..9e87c3b 100644
--- a/REFERENCE.md
+++ b/LANGUAGE.md
@@ -1,8 +1,5 @@
-Anselme reference
-=================
-
-Language reference
-------------------
+Anselme language reference
+==========================
 
 ### Main structure
 
@@ -940,13 +937,8 @@ This only works on strings:
 
 Variables for default types (each is associated to a string of the internal variable type name): `nil`, `number`, `string`, `list`, `pair`, `function reference`, `variable reference`.
 
-#### Built-in languages
+#### Built-in language scripts
 
 Anselme provides some scripts that define translated aliases for built-in variables and functions. Currently `enUS` (English) and `frFR` (French) are provided.
 
 See the `stdlib/languages` for details on each language.
-
-API reference
--------------
-
-TODO see anselme.lua
diff --git a/README.md b/README.md
index 038163d..401a4d4 100644
--- a/README.md
+++ b/README.md
@@ -68,4 +68,6 @@ TODO: stupidly complex script
 Reference
 ------------------
 
-See [REFERENCE.md](REFERENCE.md).
+See [LANGUAGE.md](LANGUAGE.md) for a reference of the language.
+
+See [API.md](API.md) for the Lua API's documentation.
diff --git a/anselme.lua b/anselme.lua
index 3d74275..f38a191 100644
--- a/anselme.lua
+++ b/anselme.lua
@@ -1,6 +1,6 @@
 -- anselme module
 local anselme = {
-	-- version
+	--- version
 	-- save is incremented a each update which may break save compatibility
 	-- language is incremented a each update which may break script file compatibility
 	-- api is incremented a each update which may break Lua API compatibility
@@ -9,7 +9,7 @@ local anselme = {
 		language = 21,
 		api = 4
 	},
-	-- version is incremented at each update
+	--- version is incremented at each update
 	version = 22,
 	--- currently running interpreter
 	running = nil
@@ -63,11 +63,12 @@ end
 
 --- interpreter methods
 local interpreter_methods = {
-	-- interpreter state
+	--- interpreter state
+	-- for internal use, you shouldn't touch this
 	state = nil,
-	-- VM this interpreter belongs to
+	--- VM this interpreter belongs to
 	vm = nil,
-	-- event that stopped the interpreter
+	--- event that stopped the interpreter
 	end_event = nil,
 
 	--- run the VM until the next event
@@ -211,10 +212,12 @@ interpreter_methods.__index = interpreter_methods
 
 --- vm methods
 local vm_mt = {
-	-- anselme state
+	--- anselme state
+	-- for internal use, you shouldn't touch this
 	state = nil,
 
-	-- loaded game state
+	--- loaded game state
+	-- for internal use, you shouldn't touch this
 	game = nil,
 
 	--- wrapper for loading a whole set of scripts