diff --git a/README.md b/README.md
index aa7dee9ff6..0c2386207d 100644
--- a/README.md
+++ b/README.md
@@ -942,8 +942,8 @@ For vertical or horizontal arrows, the **x** option can be specified as shorthan
 
 The arrow mark supports the [standard mark options](#marks). The **stroke** defaults to currentColor. The **fill** defaults to none. The **strokeWidth** defaults to 1.5, and the **strokeMiterlimit** defaults to one. The following additional options are supported:
 
-* **bend** - the bend angle, in degrees; defaults to zero
-* **headAngle** - the arrowhead angle, in degrees; defaults to 22.5°
+* **bend** - the bend angle, in degrees; defaults to zero; true for 22.5°
+* **headAngle** - the arrowhead angle, in degrees; defaults to 60°
 * **headLength** - the arrowhead scale; defaults to 8
 * **insetEnd** - inset at the end of the arrow (useful if the arrow points to a dot)
 * **insetStart** - inset at the start of the arrow
diff --git a/src/inset.d.ts b/src/inset.d.ts
index e035f9b041..f7db2f0e60 100644
--- a/src/inset.d.ts
+++ b/src/inset.d.ts
@@ -1,10 +1,10 @@
 /** Options for insetting rectangular shapes. */
 export interface InsetOptions {
   /**
-   * Shorthand to set the same default for all four insets: insetTop,
-   * insetRight, insetBottom, and insetLeft. All insets typically default to
-   * zero, though not always (say, a rect mark and a ban transform). A positive
-   * inset reduces effective area, while a negative inset increases it.
+   * Shorthand to set the same default for all four insets: **insetTop**,
+   * **insetRight**, **insetBottom**, and **insetLeft**. All insets typically
+   * default to zero, though not always (say when using bin transform). A
+   * positive inset reduces effective area, while a negative inset increases it.
    */
   inset?: number;
 
diff --git a/src/marks/arrow.d.ts b/src/marks/arrow.d.ts
index d2c9d65771..d2bf620dc5 100644
--- a/src/marks/arrow.d.ts
+++ b/src/marks/arrow.d.ts
@@ -1,21 +1,102 @@
 import type {ChannelValueSpec} from "../channel.js";
 import type {Data, MarkOptions, RenderableMark} from "../mark.js";
 
+/** Options for the arrow mark. */
 export interface ArrowOptions extends MarkOptions {
+  /**
+   * The horizontal position, for vertical arrows; typically bound to the *x*
+   * scale; shorthand for setting defaults for both **x1** and **x2**.
+   */
   x?: ChannelValueSpec;
+
+  /**
+   * The vertical position, for horizontal arrows; typically bound to the *y*
+   * scale; shorthand for setting defaults for both **y1** and **y2**.
+   */
   y?: ChannelValueSpec;
+
+  /**
+   * The starting horizontal position; typically bound to the *x* scale; also
+   * sets a default for **x2**.
+   */
   x1?: ChannelValueSpec;
+
+  /**
+   * The starting vertical position; typically bound to the *y* scale; also sets
+   * a default for **y2**.
+   */
   y1?: ChannelValueSpec;
+
+  /**
+   * The ending horizontal position; typically bound to the *x* scale; also sets
+   * a default for **x1**.
+   */
   x2?: ChannelValueSpec;
+
+  /**
+   * The ending vertical position; typically bound to the *y* scale; also sets a
+   * default for **y1**.
+   */
   y2?: ChannelValueSpec;
+
+  /**
+   * The angle, a constant in degrees, between the straight line intersecting
+   * the arrow’s two control points and the outgoing tangent direction of the
+   * arrow from the start point. The angle must be within ±90°; a positive angle
+   * will produce a clockwise curve, while a negative angle will produce a
+   * counterclockwise curve; zero (the default) will produce a straight line.
+   * Use true for 22.5°.
+   */
   bend?: number | boolean;
+
+  /**
+   * How pointy the arrowhead is, in degrees; a constant typically between 0°
+   * and 180°, and defaults to 60°.
+   */
   headAngle?: number;
+
+  /**
+   * The size of the arrowhead relative to the **strokeWidth**; a constant.
+   * Assuming the default of stroke width 1.5px, this is the length of the
+   * arrowhead’s side in pixels.
+   */
   headLength?: number;
+
+  /**
+   * Shorthand to set the same default for **insetStart** and **insetEnd**.
+   */
   inset?: number;
+
+  /**
+   * The starting inset, a constant in pixels; defaults to 0. A positive inset
+   * shortens the arrow by moving the starting point towards the endpoint point,
+   * while a negative inset extends it by moving the starting point in the
+   * opposite direction. A positive starting inset may be useful if the arrow
+   * emerges from a dot.
+   */
   insetStart?: number;
+
+  /**
+   * The ending inset, a constant in pixels; defaults to 0. A positive inset
+   * shortens the arrow by moving the ending point towards the starting point,
+   * while a negative inset extends it by moving the ending point in the
+   * opposite direction. A positive ending inset may be useful if the arrow
+   * points to a dot.
+   */
   insetEnd?: number;
 }
 
+/**
+ * Returns a new arrow mark for the given *data* and *options*, drawing
+ * (possibly swoopy) arrows connecting pairs of points. For example, to draw an
+ * arrow connecting an observation from 1980 with an observation from 2015 in a
+ * scatterplot of population and revenue inequality of U.S. cities:
+ *
+ * ```js
+ * Plot.arrow(inequality, {x1: "POP_1980", y1: "R90_10_1980", x2: "POP_2015", y2: "R90_10_2015", bend: true})
+ * ```
+ */
 export function arrow(data?: Data, options?: ArrowOptions): Arrow;
 
+/** The arrow mark. */
 export class Arrow extends RenderableMark {}
diff --git a/src/marks/link.d.ts b/src/marks/link.d.ts
index 33dc34576b..f085b00516 100644
--- a/src/marks/link.d.ts
+++ b/src/marks/link.d.ts
@@ -59,7 +59,7 @@ export interface LinkOptions extends MarkOptions, MarkerOptions, CurveAutoOption
 
 /**
  * Returns a new link mark for the given *data* and *options*, drawing line
- * segments (curves) to connect pairs of points. For example, to draw a link
+ * segments (curves) connecting pairs of points. For example, to draw a link
  * connecting an observation from 1980 with an observation from 2015 in a
  * scatterplot of population and revenue inequality of U.S. cities:
  *