Vector functions: Fix vector.direction() function, improve documentation (#6801)

vector.direction() now returns a normalised vector with direction p1 to p2.

doc/lua_api.txt

@@ -2248,25 +2248,43 @@ The following functions provide escape sequences:
 
 Spatial Vectors
 ---------------
-* `vector.new(a[, b, c])`: returns a vector:
+For the following functions, `v`, `v1`, `v2` are vectors, `p1`, `p2` are positions:
+
+* `vector.new(a[, b, c])`:
+    * Returns a vector.
     * A copy of `a` if `a` is a vector.
-    * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
-* `vector.direction(p1, p2)`: returns a vector
-* `vector.distance(p1, p2)`: returns a number
-* `vector.length(v)`: returns a number
-* `vector.normalize(v)`: returns a vector
-* `vector.floor(v)`: returns a vector, each dimension rounded down
-* `vector.round(v)`: returns a vector, each dimension rounded to nearest int
-* `vector.apply(v, func)`: returns a vector
-* `vector.equals(v1, v2)`: returns a boolean
-* `vector.sort(v1, v2)`: returns minp, maxp vectors of the cuboid defined by v1 and v2
+    * `{x = a, y = b, z = c}`, if all of `a`, `b`, `c` are defined numbers.
+* `vector.direction(p1, p2)`:
+    * Returns a vector of length 1 with direction `p1` to `p2`.
+    * If `p1` and `p2` are identical, returns `{x = 0, y = 0, z = 0}`.
+* `vector.distance(p1, p2)`:
+    * Returns zero or a positive number, the distance between `p1` and `p2`.
+* `vector.length(v)`:
+    * Returns zero or a positive number, the length of vector `v`.
+* `vector.normalize(v)`:
+    * Returns a vector of length 1 with direction of vector `v`.
+    * If `v` has zero length, returns `{x = 0, y = 0, z = 0}`.
+* `vector.floor(v)`:
+    * Returns a vector, each dimension rounded down.
+* `vector.round(v)`:
+    * Returns a vector, each dimension rounded to nearest integer.
+* `vector.apply(v, func)`:
+    * Returns a vector where the function `func` has been applied to each component.
+* `vector.equals(v1, v2)`:
+    * Returns a boolean, `true` if the vectors are identical.
+* `vector.sort(v1, v2)`:
+    * Returns in order minp, maxp vectors of the cuboid defined by `v1`, `v2`.
 
 For the following functions `x` can be either a vector or a number:
 
-* `vector.add(v, x)`: returns a vector
-* `vector.subtract(v, x)`: returns a vector
-* `vector.multiply(v, x)`: returns a scaled vector or Schur product
-* `vector.divide(v, x)`: returns a scaled vector or Schur quotient
+* `vector.add(v, x)`:
+    * Returns a vector.
+* `vector.subtract(v, x)`:
+    * Returns a vector.
+* `vector.multiply(v, x)`:
+    * Returns a scaled vector or Schur product.
+* `vector.divide(v, x)`:
+    * Returns a scaled vector or Schur quotient.
 
 Helper functions
 ----------------