first half of Point docs update

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

@@ -1,14 +1,15 @@
 ---
-title: angle()
+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.
+
 ```js
 float point.angle(Point point)
-``` 
+```
 
-Returns the angle made by a line from this point to the point you pass it.
+<Example
-
-<Example 
   part="point_angle"
   caption="An example of the Point.angle() method"
 />
@@ -28,4 +29,3 @@ paths.line = new Path()
   .line(points.moon)
   .attr("class", "dashed");
 ```
-

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

@@ -1,7 +1,10 @@
 ---
-title: attr()
+title: Point.attr()
 ---
 
+A point's `attr()` method adds an attribute to the point, and returns the point. Setting the third parameter
+to `true` will replace the value of the attribute instead of adding it.
+
 ```js
 Point point.attr(
   string name, 
@@ -10,12 +13,12 @@ Point point.attr(
 )
 ```
 
-This `Point.attr()` method calls `this.attributes.add()` under the hood, but returns the Point object.
+The `Point.attr()` method calls [`this.attributes.add()`](/reference/api/attributes/add/) under the hood, but returns the `Point` object.
 This allows you to chain different calls together as in the example below.
 
-If the third parameter is set to `true` it will call `this.attributes.set()` instead, thereby overwriting the value of the attribute.
+If the third parameter is set to `true` it will call [`this.attributes.set()`](/reference/api/attributes/set/) instead, thereby overwriting the value of the attribute.
 
-<Example 
+<Example
   part="point_attr"
   caption="An example of the Point.attr() method"
 />
@@ -27,4 +30,3 @@ points.anchor = new Point(100, 25)
   .attr("data-text", "freesewingIsMadeByJoostDeCockAndContributors")
   .attr("data-text-class", "center");
 ```
-

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

@@ -1,23 +1,23 @@
 ---
-title: clone()
+title: Point.clone()
 ---
 
-```
+A point's `clone()` method returns a new `Point` with the same coordinates and attributes as the original point.
+
+```js
 Point point.clone()
 ```
 
-Returns a new point with the same coordinates and attributes as this point.
-
 <Note>
 
 ###### Copy vs clone
 
-The `Point.copy()` method will only copy the point's coordinates, whereas this
+The [`Point.copy()`](reference/api/point/copy/) method will only copy the point's coordinates, whereas this
 `Point.clone()` method will also copy its attributes.
 
 </Note>
 
-<Example 
+<Example
   part="point_clone"
   caption="An example of the Point.clone() method"
 />
@@ -33,4 +33,3 @@ The `Point.copy()` method will only copy the point's coordinates, whereas this
 
   snippets.x = new Snippet("notch", points.A);
 ```
-

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

@@ -1,14 +1,23 @@
 ---
-title: copy()
+title: Point.copy()
 ---
+A point's `copy()` method returns a new point with the same coordinates as the original point.
+This method does _not_ copy any attributes the original point may have.
 
 ```js
 Point point.copy()
 ```
 
-Returns a new point with the same coordinates as this point.
+<Note>
 
-<Example 
+###### Copy vs clone
+
+this `Point.copy()` method will only copy the point's coordinates.
+To also copy the attributes, use [`Point.clone()`](reference/api/point/clone/) instead.
+
+</Note>
+
+<Example
   part="point_copy"
   caption="An example of the Point.copy() method"
 />
@@ -23,4 +32,3 @@ points.B = points.A.copy().attr("data-text", "Point B");
 
 snippets.x = new Snippet("notch", points.A);
 ```
-

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

@@ -1,14 +1,14 @@
 ---
-title: dx()
+title: Point.dx()
 ---
 
+A point's `dx()` method returns the delta (in mm) along the X-axis between this point and the point you pass it.
+
 ```js
 float point.dx(Point point)
 ```
 
-Returns the delta along the X-axis between this point and the point you pass it.
+<Example
-
-<Example 
   part="point_dx"
   caption="An example of the Point.dx() method"
 />
@@ -42,4 +42,3 @@ paths.line_dy = new Path()
   .line(points.totop)
   .attr("class", "dashed")
 ```
-

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

@@ -1,14 +1,14 @@
 ---
-title: dy()
+title: Point.dy()
 ---
 
+A point's `dy()` method returns the delta (in mm) along the Y-axis between this point and the point you pass it.
+
 ```js
 float point.dy(Point point)
 ```
 
-Returns the delta along the Y-axis between this point and the point you pass it.
+<Example
-
-<Example 
   part="point_dy"
   caption="An example of the Point.dy() method"
 />

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

@@ -1,16 +1,15 @@
 ---
-title: flipX()
+title: Point.flipX()
 ---
 
+A point's `flipX()` method returns a new `Point` that mirrors the original point around the X-value of the point you pass it.
+If you do not pass in a point, it will default to mirroring around an X-value of zero.
+
 ```js
 Point point.flipX(Point mirror = false)
 ```
 
-Returns a new point that mirrors this point around the X-value of the point your pass it.
+<Example
-
-If you don't pass it a point, it will mirror around an X-value of zero.
-
-<Example 
   part="point_flipx"
   caption="An example of the Point.flipX() method"
 />
@@ -61,4 +60,3 @@ paths.mirror = new Path()
   .line(points.bottom)
   .attr("class", "note dashed");
 ```
-

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

@@ -1,18 +1,15 @@
 ---
-title: flipY()
+title: Point.flipY()
 ---
 
+A point's `flipY()` method returns a new `Point` that mirrors the original point around the Y-value of the point you pass it.
+If you do not pass in a point, it will default to mirroring around an Y-value of zero.
+
 ```js
 Point point.flipY(Point mirror = false)
 ```
 
-Returns a new point that mirrors this point around the Y-value of the point your pass it.
+<Example
-
-If you don't pass it a point, it will mirror around a Y-value of zero.
-
-### Point.flipY() example
-
-<Example 
   part="point_flipy"
   caption="An example of the Point.flipY() method"
 />
@@ -68,4 +65,3 @@ paths.skylineTop = new Path()
   .line(points.houseWallRight)
   .line(points.end);
 ```
-

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

@@ -1,14 +1,17 @@
 ---
-title: rotate()
+title: Point.rotate()
 ---
 
+A point's `rotate()` method returns a new `Point` that has been rotated by `angle` degrees
+around the point (`center`) that you pass it.
+
+Just like the result of the [`Point.angle()`](reference/api/point/angle/) method, an angle of 0° points right, and the angle increases counterclockwise.
+
 ```js
 Point point.rotate(float angle, Point center)
-``` 
+```
 
-Rotates a point the number of degrees you pass it around the point you pass it.
+<Example
-
-<Example 
   part="point_rotate"
   caption="An example of the Point.rotate() method"
 />