Improve lua vector helper class doumentation (#12090)

1 files changed, 81 insertions, 23 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 89bc7dc4b..52da17e9c 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -1544,15 +1544,12 @@ Displays a minimap on the HUD.
 Representations of simple things
 ================================
 
-Position/vector
----------------
-
-    {x=num, y=num, z=num}
+Vector (ie. a position)
+-----------------------
 
-    Note: it is highly recommended to construct a vector using the helper function:
-    vector.new(num, num, num)
+    vector.new(x, y, z)
 
-For helper functions see [Spatial Vectors].
+See [Spatial Vectors] for details.
 
 `pointed_thing`
 ---------------
@@ -1573,8 +1570,7 @@ Exact pointing location (currently only `Raycast` supports these fields):
   from 1).
 * `pointed_thing.intersection_normal`: Unit vector, points outwards of the
   selected selection box. This specifies which face is pointed at.
-  Is a null vector `{x = 0, y = 0, z = 0}` when the pointer is inside the
-  selection box.
+  Is a null vector `vector.zero()` when the pointer is inside the selection box.
 
 
 
@@ -3303,33 +3299,76 @@ The following functions provide escape sequences:
 
 Spatial Vectors
 ===============
-A spatial vector is similar to a position, but instead using
-absolute world coordinates, it uses *relative* coordinates, relative to
-no particular point.
-
-Internally, it is implemented as a table with the 3 fields
-`x`, `y` and `z`. Example: `{x = 0, y = 1, z = 0}`.
-However, one should *never* create a vector manually as above, such misbehavior
-is deprecated. The vector helpers set a metatable for the created vectors which
-allows indexing with numbers, calling functions directly on vectors and using
-operators (like `+`). Furthermore, the internal implementation might change in
+
+Minetest stores 3-dimensional spatial vectors in Lua as tables of 3 coordinates,
+and has a class to represent them (`vector.*`), which this chapter is about.
+For details on what a spatial vectors is, please refer to Wikipedia:
+https://en.wikipedia.org/wiki/Euclidean_vector.
+
+Spatial vectors are used for various things, including, but not limited to:
+
+* any 3D spatial vector (x/y/z-directions)
+* Euler angles (pitch/yaw/roll in radians) (Spatial vectors have no real semantic
+  meaning here. Therefore, most vector operations make no sense in this use case.)
+
+Note that they are *not* used for:
+
+* n-dimensional vectors where n is not 3 (ie. n=2)
+* arrays of the form `{num, num, num}`
+
+The API documentation may refer to spatial vectors, as produced by `vector.new`,
+by any of the following notations:
+
+* `(x, y, z)` (Used rarely, and only if it's clear that it's a vector.)
+* `vector.new(x, y, z)`
+* `{x=num, y=num, z=num}` (Even here you are still supposed to use `vector.new`.)
+
+Compatibility notes
+-------------------
+
+Vectors used to be defined as tables of the form `{x = num, y = num, z = num}`.
+Since Minetest 5.5.0, vectors additionally have a metatable to enable easier use.
+Note: Those old-style vectors can still be found in old mod code. Hence, mod and
+engine APIs still need to be able to cope with them in many places.
+
+Manually constructed tables are deprecated and highly discouraged. This interface
+should be used to ensure seamless compatibility between mods and the Minetest API.
+This is especially important to callback function parameters and functions overwritten
+by mods.
+Also, though not likely, the internal implementation of a vector might change in
 the future.
-Old code might still use vectors without metatables, be aware of this!
+In your own code, or if you define your own API, you can, of course, still use
+other representations of vectors.
+
+Vectors provided by API functions will provide an instance of this class if not
+stated otherwise. Mods should adapt this for convenience reasons.
+
+Special properties of the class
+-------------------------------
+
+Vectors can be indexed with numbers and allow method and operator syntax.
 
 All these forms of addressing a vector `v` are valid:
 `v[1]`, `v[3]`, `v.x`, `v[1] = 42`, `v.y = 13`
+Note: Prefer letter over number indexing for performance and compatibility reasons.
 
 Where `v` is a vector and `foo` stands for any function name, `v:foo(...)` does
 the same as `vector.foo(v, ...)`, apart from deprecated functionality.
 
+`tostring` is defined for vectors, see `vector.to_string`.
+
 The metatable that is used for vectors can be accessed via `vector.metatable`.
 Do not modify it!
 
 All `vector.*` functions allow vectors `{x = X, y = Y, z = Z}` without metatables.
 Returned vectors always have a metatable set.
 
-For the following functions, `v`, `v1`, `v2` are vectors,
-`p1`, `p2` are positions,
+Common functions and methods
+----------------------------
+
+For the following functions (and subchapters),
+`v`, `v1`, `v2` are vectors,
+`p1`, `p2` are position vectors,
 `s` is a scalar (a number),
 vectors are written like this: `(x, y, z)`:
 
@@ -3351,6 +3390,7 @@ vectors are written like this: `(x, y, z)`:
     * `init`: If given starts looking for the vector at this string index.
 * `vector.to_string(v)`:
     * Returns a string of the form `"(x, y, z)"`.
+    *  `tostring(v)` does the same.
 * `vector.direction(p1, p2)`:
     * Returns a vector of length 1 with direction `p1` to `p2`.
     * If `p1` and `p2` are identical, returns `(0, 0, 0)`.
@@ -3403,6 +3443,9 @@ For the following functions `x` can be either a vector or a number:
     * Returns a scaled vector.
     * Deprecated: If `s` is a vector: Returns the Schur quotient.
 
+Operators
+---------
+
 Operators can be used if all of the involved vectors have metatables:
 * `v1 == v2`:
     * Returns whether `v1` and `v2` are identical.
@@ -3419,8 +3462,11 @@ Operators can be used if all of the involved vectors have metatables:
 * `v / s`:
     * Returns `v` scaled by `1 / s`.
 
+Rotation-related functions
+--------------------------
+
 For the following functions `a` is an angle in radians and `r` is a rotation
-vector ({x = <pitch>, y = <yaw>, z = <roll>}) where pitch, yaw and roll are
+vector (`{x = <pitch>, y = <yaw>, z = <roll>}`) where pitch, yaw and roll are
 angles in radians.
 
 * `vector.rotate(v, r)`:
@@ -3437,6 +3483,18 @@ angles in radians.
     * If `up` is omitted, the roll of the returned vector defaults to zero.
     * Otherwise `direction` and `up` need to be vectors in a 90 degree angle to each other.
 
+Further helpers
+---------------
+
+There are more helper functions involving vectors, but they are listed elsewhere
+because they only work on specific sorts of vectors or involve things that are not
+vectors.
+
+For example:
+
+* `minetest.hash_node_position` (Only works on node positions.)
+* `minetest.dir_to_wallmounted` (Involves wallmounted param2 values.)
+