diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua
index 8c52a8a2c..ed9727a69 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua
@@ -851,13 +851,32 @@ unserialise = unserialize -- GB version
 
 --[[- Returns a JSON representation of the given data.
 
-This function attempts to guess whether a table is a JSON array or
-object. However, empty tables are assumed to be empty objects - use
-[`textutils.empty_json_array`] to mark an empty array.
-
 This is largely intended for interacting with various functions from the
 [`commands`] API, though may also be used in making [`http`] requests.
 
+Lua has a rather different data model to Javascript/JSON. As a result, some Lua
+values do not serialise cleanly into JSON.
+
+ - Lua tables can contain arbitrary key-value pairs, but JSON only accepts arrays,
+   and objects (which require a string key). When serialising a table, if it only
+   has numeric keys, then it will be treated as an array. Otherwise, the table will
+   be serialised to an object using the string keys. Non-string keys (such as numbers
+   or tables) will be dropped.
+
+   A consequence of this is that an empty table will always be serialised to an object,
+   not an array. [`textutils.empty_json_array`] may be used to express an empty array.
+
+ - Lua strings are an a sequence of raw bytes, and do not have any specific encoding.
+   However, JSON strings must be valid unicode. By default, non-ASCII characters in a
+   string are serialised to their unicode code point (for instance, `"\xfe"` is
+   converted to `"\u00fe"`). The `unicode_strings` option may be set to treat all input
+   strings as UTF-8.
+
+ - Lua does not distinguish between missing keys (`undefined` in JS) and ones explicitly
+   set to `null`. As a result `{ x = nil }` is serialised to `{}`. [`textutils.json_null`]
+   may be used to get an explicit null value (`{ x = textutils.json_null }` will serialise
+   to `{"x": null}`).
+
 @param[1] t The value to serialise. Like [`textutils.serialise`], this should not
 contain recursive tables or functions.
 @tparam[1,opt] {