more point docs updates

markdown/dev/reference/api/point/angle/en.md

@@ -5,10 +5,14 @@ title: Point.angle()
 A point's `angle()` method returns the angle (in degrees) between this point and
 the point passed into the method. An angle of 0° points to the right, and the angle increases counterclockwise.
 
+## Point.angle() signature
+
 ```js
-float point.angle(Point point)
+float point.angle(Point pointB)
 ```
 
+## Point.angle() Example
+
 <Example
   part="point_angle"
   caption="An example of the Point.angle() method"

markdown/dev/reference/api/point/attr/en.md

@@ -2,7 +2,7 @@
 title: Point.attr()
 ---
 
-A point's `attr()` method adds an attribute to the point, and returns the point. Setting the third parameter
+Adds an attribute to the point, and returns the original point. Setting the third parameter
 to `true` will replace the value of the attribute instead of adding it.
 
 ```js

markdown/dev/reference/api/point/clone/en.md

@@ -2,7 +2,7 @@
 title: Point.clone()
 ---
 
-A point's `clone()` method returns a new `Point` with the same coordinates and attributes as the original point.
+Returns a new `Point` with the same coordinates and attributes as the original point.
 
 ```js
 Point point.clone()

markdown/dev/reference/api/point/shift/en.md

@@ -1,14 +1,15 @@
 ---
-title: shift()
+title: Point.shift()
 ---
 
+Returns a new `Point` that is `distance` (mm) away in the direction of `angle` (degrees).
+An angle of 0° points to the right, and the angle increases counterclockwise.
+
 ```js
-Point point.shift(float degrees, float distance)
+Point point.shift(float angle, float distance)
 ```
 
-Returns a point that lies distance in the direction of degrees from this point.
-
-<Example 
+<Example
   part="point_shift"
   caption="An example of the Point.shift() method"
 />

markdown/dev/reference/api/point/shiftfractiontowards/en.md

@@ -1,14 +1,20 @@
 ---
-title: shiftFractionTowards()
+title: Point.shiftFractionTowards()
 ---
 
+Returns a new `Point` that is shifted towards the `target` by a `fraction` of the distance between this
+point and the target.
+
+This method accepts values larger than 1 to go beyond the target point, or negative values to shift the
+point in the opposite direction.
+
+If you need to move a point by a specific distance instead of a percentage, use [`Point.shiftTowards()`]((reference/api/point/shifttowards/)) or [`Point.shiftOutwards()`](reference/api/point/shiftoutwards/) instead.
+
 ```js
 Point point.shiftFractionTowards(Point target, float fraction)
 ```
 
-Returns a point that is shifted towards the target by a fraction of the distance between this point and the target.
-
-<Example 
+<Example
   part="point_shiftfractiontowards"
   caption="An example of the Point.shiftFractionTowards() method"
 />

markdown/dev/reference/api/point/shiftoutwards/en.md

@@ -1,14 +1,14 @@
 ---
-title: shiftOutwards()
+title: Point.shiftOutwards()
 ---
 
+Returns a new `Point` that is shifted `distance` (mm) beyond the `target` in the direction of the target point.
+
 ```js
-Point point.shiftOutwards(Point direction, float distance)
+Point point.shiftOutwards(Point target, float distance)
 ```
 
-Returns a point that is shifted distance beyond target in the direction of target.
-
-<Example 
+<Example
   part="point_shiftoutwards"
   caption="An example of the Point.shiftOutwards() method"
 />

markdown/dev/reference/api/point/shifttowards/en.md

@@ -1,14 +1,16 @@
 ---
-title: shiftTowards()
+title: Point.shiftTowards()
 ---
 
+Returns a new `Point` that is shifted `distance` (mm) in the direction of the `target`.
+
+If you need to move a point a percentage instead of a specific distance, use [`Point.shiftFractionTowards()`](reference/api/point/shiftfractiontowards/) instead.
+
 ```js
 Point point.shiftTowards(Point target, float distance)
 ```
 
-Returns a point that lies distance in the direction of target.
-
-<Example 
+<Example
   part="point_shifttowards"
   caption="An example of the Point.shiftTowards() method"
 />

markdown/dev/reference/api/point/sitson/en.md

@@ -1,14 +1,26 @@
 ---
-title: sitsOn()
+title: Point.sitsOn()
 ---
 
+Returns `true` if this point has the _exact_ same coordinates as the point you pass to it.
+
+<Note>
+
+###### Too exact?
+
+This method is _very_ precise, so points with an X-coordinate of `10` and `10.0001`
+are considered to be different.
+
+To check if two points have the same coordinates rounded to the nearest
+millimeter, use [`Point.sitsRoughlyOn()`](/reference/api/point/sitsroughlyon/) instead.
+
+</Note>
+
 ```js
 bool point.sitsOn(Point check)
 ```
 
-Returns true if the point has the same coordinates as the one you pass to it.
-
-<Example 
+<Example
   part="point_sitson"
   caption="An example of the Point.sitsOn() method"
 />

markdown/dev/reference/api/point/sitsroughlyon/en.md

@@ -1,18 +1,18 @@
 ---
-title: sitsRoughlyOn()
+title: Point.sitsRoughlyOn()
 ---
 
+Returns `true` if this point has roughly (rounded to the nearest millimeter) the same coordinates as the one you pass to it.
+
 ```js
 bool point.sitsRoughlyOn(Point check)
 ```
 
-Returns true is the point has roughly the same coordinates as the one you pass to it.
-
 <Note>
 
 ###### How rough?
 
-The difference between this method and [Point.sitsOn](/reference/api/point/sitson/) is 
+The difference between this method and [`Point.sitsOn()`](/reference/api/point/sitson/) is
 that this one rounds things down to the nearest integer (thus mm) before checking.
 
 </Note>

markdown/dev/reference/api/point/translate/en.md

@@ -1,21 +1,21 @@
 ---
-title: translate()
+title: Point.translate()
 ---
- 
+
+Returns a new `Point` with a [translate transform](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/translate) applied.
+
 ```js
 Point point.translate(float deltaX, float deltaY)
 ```
 
-Returns a point with 
-[a translate transform](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/translate) 
-applied. 
-
 In other words, this will:
 
- - Add `deltaX` to the point's X-coordinate
- - Add `deltaY` to the point's Y-coordinate
+- Add `deltaX` to the point's X-coordinate
+- Add `deltaY` to the point's Y-coordinate
 
-<Example 
+Positive values for `deltaX` will move the point to the right. Positive values for `deltaY` will move the point downwards.
+
+<Example
   part="point_translate"
   caption="An example of the Point.translate() method"
 />