Vector API: edit

pages/Vector_API.md

@@ -5,29 +5,29 @@ Do note that functions here will accept an old-style (non-metatable) `vector`, b
 
 TIP: The respective source code is located [here](https://github.com/minetest/minetest/blob/master/builtin/common/vector.lua).
 
+[toc]
+
 ## `vector` Namespace
 
-### `vector.new(a, b, c) -> vector`
+### `vector.new(a, b, c)`
 * `a`: `number`, `vector`, or `nil`
 * `b`, `c`: `number` or `nil`
 
 If `a`, `b`, and `c` are `number`: Returns a new `vector` where `{x = a, y = b, z = c}`
 
-NOTE: {deprecated}
+Deprecated behaviours:
+- If `a` is a `vector`: Returns `vector.copy(a)`
+- If all parameters are `nil`: Returns `vector.zero()`
 
-If `a` is a `vector`: Returns `vector.copy(a)`
-
-If all parameters are `nil`: Returns `vector.zero()`
-
-### `vector.zero() -> vector`
+### `vector.zero()`
 Returns a new `vector` where `{x = 0, y = 0, z = 0}`
 
-### `vector.copy(v) -> vector`
+### `vector.copy(v)`
 * `v`: `vector`
 
 Returns a new `vector` where `{x = v.x, y = v.y, z = v.z}`. This is *not* equivalent to `table.copy`, as that does not set the `vector` metatable.
 
-### `vector.from_string(s, init) -> vector, number`
+### `vector.from_string(s, init)`
 * `s`: `string`
 * `init`: `number`
 
@@ -37,28 +37,28 @@ Expects `s` to be in the following format: `(x, y, z)` where `x`, `y`, and `z` a
 There are some allowances in the parsing rules for extra whitespace as padding around elements.
 You may set the position in `s` where `string.match` will begin parsing via `init`.
 
-### `vector.to_string(v) -> string`
+### `vector.to_string(v)`
 * `v`: `vector`
 
 Returns a `string` representation of `v` in the format: `(v.x, v.y, v.z)`.
 
 Each component is formatted with the printf-style `%g` flag (either floating-point or scientific notation, whichever is shorter).
 
-### `vector.equals(a, b) -> bool`
+### `vector.equals(a, b)`
 * `a`, `b`: `vector`
 
 Returns `true` if `a` is equivalent to `b` (all components are the same).
 
 Returns `false` otherwise.
 
-### `vector.length(v) -> number`
+### `vector.length(v)`
 * `v`: `vector`
 
 Returns the vectorial length (total traveled traveled distance from the origin to the end) of `v`.
 
 The formula for the length is: `sqrt(x^2 + y^2 + z^2)`.
 
-### `vector.normalize(v) -> vector`
+### `vector.normalize(v)`
 * `v`: `vector`
 
 Returns a new `vector` which is the normalized form of `v` (the vectorial length is equal to 1).
@@ -67,27 +67,27 @@ Uses `vector.length(v)` to get the vectorial length.
 Specifically, if the length is 0, returns a new `vector` with all components being `0`.
 Otherwise, returns `vector.divide(v, length)`.
 
-### `vector.floor(v) -> vector`
+### `vector.floor(v)`
 * `v`: `vector`
 
 Returns a new `vector` where each component of `v` has had `math.floor` applied to it.
 
 Literally `vector.apply(v, math.floor)`.
 
-### `vector.round(v) -> vector`
+### `vector.round(v)`
 * `v`: `vector`
 
 Returns a new `vector` where each component of `v` has had `math.round` applied to it.
 
 Equivalent to `vector.apply(v, math.round)`
 
-### `vector.apply(v, func) -> vector`
+### `vector.apply(v, func)`
 * `v`: `vector`
 * `func`: `function`
 
 Returns a new `vector` where each component of `v` has had `func` applied to it.
 
-### `vector.combine(v, w, func) -> vector`
+### `vector.combine(v, w, func)`
 * `v`: `vector`
 * `w`: `vector`
 * `func`: `function`
@@ -96,36 +96,36 @@ Returns a new `vector` where each pair of respective components of `v` and `w` h
 
 Example: `vector.combine(v, w, math.pow)` is the same as `vector.new(math.pow(v.x, w.x), math.pow(v.y, w.y), math.pow(v.z, w.z))`.
 
-### `vector.distance(a, b) -> number`
+### `vector.distance(a, b)`
 * `a`, `b`: `vector`
 
 Returns a `number` which is equal to the distance between `a` and `b`.
 
 Distance is equal to the scalar (single number) result of `|bar a - bar b|`.
 
-### `vector.direction(pos1, pos2) -> vector`
+### `vector.direction(pos1, pos2)`
 * `pos1`, `pos2`: `vector`
 
 Returns a new, normalized `vector` equal to the direction from `pos1` to `pos2`.
 
-### `vector.angle(a, b) -> number`
+### `vector.angle(a, b)`
 * `a`, `b`: `vector`
 
 Returns a `number` which is equal to the angle (in radians) between `a` and `b`.
 
 Formula used is `tan^-1(|bar a xx bar b|, bar a * bar b)`.
 
-### `vector.dot(a, b) -> number`
+### `vector.dot(a, b)`
 * `a`, `b`: `vector`
 
 Returns a `number` equal to the dot product of `a` and `b`.
 
-### `vector.cross(a, b) -> vector`
+### `vector.cross(a, b)`
 * `a`, `b`: `vector`
 
 Returns a new `vector` which is equal to the cross product of `a` and `b`.
 
-### `vector.add(a, b) -> vector`
+### `vector.add(a, b)`
 * `a`: `vector`
 * `b`: `vector` or `number`
 
@@ -133,7 +133,7 @@ If `b` is a `vector`: Returns a new `vector` where each component of `b` is adde
 
 If `b` is a `number`: Returns a new `vector` where `b` is added to each component of `a`
 
-### `vector.subtract(a, b) -> vector`
+### `vector.subtract(a, b)`
 * `a`: `vector`
 * `b`: `vector` or `number`
 
@@ -141,7 +141,7 @@ If `b` is a `vector`: Returns a new `vector` where each component of `b` is subt
 
 If `b` is a `number`: Returns a new `vector` where `b` is subtracted from each component of `a`
 
-### `vector.multiply(a, b) -> vector`
+### `vector.multiply(a, b)`
 * `a`: `vector`
 * `b`: `vector` or `number`
 
@@ -149,7 +149,7 @@ If `b` is a `vector`: Returns a new `vector` where each component of `a` is mult
 
 If `b` is a `number`: Returns a new `vector` where each component of `a` is multiplied by `b`
 
-### `vector.divide(a, b) -> vector`
+### `vector.divide(a, b)`
 * `a`: `vector`
 * `b`: `vector` or `number`
 
@@ -157,7 +157,7 @@ If `b` is a `vector`: Returns a new `vector` where each component of `a` is divi
 
 If `b` is a `number`: Returns a new `vector` where each component of `a` is divided by `b`
 
-### `vector.offset(v, x, y, z) -> vector`
+### `vector.offset(v, x, y, z)`
 * `v`: `vector`
 * `x`, `y`, `z`: `number`
 
@@ -165,7 +165,7 @@ Returns a new `vector` where each component of `x`, `y`, and `z` are added to th
 
 Equivalent to `vector.add(v, {x = x, y = y, z = z})`.
 
-### `vector.sort(a, b) -> vector, vector`
+### `vector.sort(a, b)`
 * `a`: `vector`
 * `b`: `vector`
 
@@ -175,20 +175,20 @@ The first consists of the smaller components of `a` and `b`, where each is equal
 
 The second is similar to the first, but consisting of the larger components instead.
 
-### `vector.check(v) -> bool`
+### `vector.check(v)`
 * `v`: `vector`
 
 Returns `true` if `v` is a valid, metatable-enhanced vector.
 
 Returns `false` otherwise.
 
-### `vector.rotate_around_axis(v, axis, angle) -> vector`
+### `vector.rotate_around_axis(v, axis, angle)`
 * `v`, `axis`: `vector`
 * `angle`: `number`
 
 Returns a new `vector` which is equal to `v` rotated around `axis` by `angle` radians counter-clockwise.
 
-### `vector.rotate(v, rot) -> vector`
+### `vector.rotate(v, rot)`
 * `v`, `rot`: `vector`
 
 Returns a new `vector` which is equal to `v` rotated by `rot` counter-clockwise.
@@ -199,7 +199,7 @@ The way that the components of `rot` map is as follows:
 * `rot.y` is yaw
 * `rot.z` is roll
 
-### `vector.dir_to_rotation(forward, up) -> vector`
+### `vector.dir_to_rotation(forward, up)`
 * `forward`: `vector`
 * `up`: `vector` or `nil`
 
@@ -210,7 +210,6 @@ If `up` is `nil` then the returned rotational `vector` assumed that `y = 1` is u
 Both `up` and `forward` are normalized by the function before calculations are made with them, so a call with or without normalization by the caller will be the same.
 
 ## Metatable Functions
-
 Metatable-enhanced `vector` values have some convenience features to help make vector math more readable. They can have be used with normal math operations rather than needing to call the equivalent namespaced function.
 
 They also can be indexed either with named keys (`v.x` and `v["x"]`) or they can be indexed with numeric keys (`v[1]` being `v.x`, `v[2]` being `v.y`, and `v[3]` being `v.z`).
@@ -231,31 +230,31 @@ v3 = ((v1 + v2) / 2) * 3
 v3 = vector.multiply(vector.divide(vector.add(v1, v2), 2), 3)
 ```
 
-### `metatable.__eq(a, b) -> bool`
+### `metatable.__eq(a, b)`
 * `a`, `b`: `vector`
 
 Literally `vector.equals(a, b)`.
 
-### `metatable.__unm(v) -> vector`
+### `metatable.__unm(v)`
 * `v`: `vector`
 
 Returns a new `vector` which is the inverse of `v`.
 
-### `metatable.__add(a, b) -> vector`
+### `metatable.__add(a, b)`
 * `a`, `b`: `vector`
 
 Returns a new `vector` where each component of `a` is added to each respective component of `b`.
 
 NOTE: Unlike `vector.add()` this does not support adding `number` values.
 
-### `metatable.__sub(a, b) -> vector`
+### `metatable.__sub(a, b)`
 * `a`, `b`: `vector`
 
 Returns a new `vector` where each component of `a` is subtracted from each respective component of `b`.
 
 NOTE: Unlike `vector.subtract()` this does not support subtracting `number` values.
 
-### `metatable.__mul(a, b) -> vector`
+### `metatable.__mul(a, b)`
 * `a`: `vector` or `number`
 * `b`: `number` or `vector`
 
@@ -263,7 +262,7 @@ Returns a new `vector` where each component of `a` is multiplied by each respect
 
 CAUTION: This function assumes that one just one argument is a number, and will probably return confusing errors about "accessing a `nil` value" if two `vector` arguments are passed to it.
 
-### `metatable.__div(a, b) -> vector`
+### `metatable.__div(a, b)`
 * `a`: `vector`
 * `b`: `number`