mark docs

Author: mbostock

src/channel.d.ts

@@ -169,6 +169,12 @@ export type ChannelValueDenseBinSpec = ChannelValue | ({value: ChannelValue; sca
  * - *width* - impute from |*x2* - *x1*|
  * - *height* - impute from |*y2* - *y1*|
  * - null - impute from input order
+ *
+ * If the *x* channel is not defined, the *x2* channel will be used instead if
+ * available, and similarly for *y* and *y2*; this is useful for marks that
+ * implicitly stack. The *data* input is typically used in conjunction with a
+ * custom **reduce** function, as when the built-in single-channel reducers are
+ * insufficient.
  */
 export type ChannelDomainValue = ChannelName | "data" | "width" | "height" | null;
 
@@ -190,12 +196,22 @@ export interface ChannelDomainOptions {
   reverse?: boolean;
 
   /**
-   * If a positive number, limit the domain to the first *n* sorted values; if a
-   * negative number, limit the domain to the last *-n* sorted values. Otherwise
-   * slices the sorted domain from *lo* (inclusive) to *hi* (exclusive); if
-   * either *lo* or *hi* are negative, it indicates an offset from the end of
-   * the array; if *lo* is undefined it defaults to 0, and if *hi* is undefined
-   * it defaults to Infinity.
+   * If a positive number, limit the domain to the first *n* sorted values. If a
+   * negative number, limit the domain to the last *-n* sorted values. Hence, a
+   * positive **limit** with **reverse** true will return the top *n* values in
+   * descending order.
+   *
+   * If an array [*lo*, *hi*], slices the sorted domain from *lo* (inclusive) to
+   * *hi* (exclusive). As with [*array*.slice][1], if either *lo* or *hi* are
+   * negative, it indicates an offset from the end of the array; if *lo* is
+   * undefined it defaults to 0, and if *hi* is undefined it defaults to
+   * Infinity.
+   *
+   * Note: limiting the imputed domain of one scale, say *x*, does not affect
+   * the imputed domain of another scale, say *y*; each scale domain is imputed
+   * independently.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice
    */
   limit?: number | [lo?: number, hi?: number];
 }

src/mark.d.ts

@@ -5,6 +5,13 @@ import type {plot} from "./plot.js";
 import type {ScaleFunctions} from "./scales.js";
 import type {InitializerFunction, SortOrder, TransformFunction} from "./transforms/basic.js";
 
+/**
+ * How to anchor a mark relative to the plot’s frame; one of:
+ *
+ * - *middle* - centered in the middle
+ * - in the middle of one of the edges: *top*, *right*, *bottom*, *left*
+ * - in one of the corners: *top-left*, *top-right*, *bottom-right*, *bottom-left*
+ */
 export type FrameAnchor =
   | "middle"
   | "top-left"
@@ -16,6 +23,12 @@ export type FrameAnchor =
   | "bottom-left"
   | "left";
 
+/**
+ * A mark’s data; one of:
+ *
+ * - an array, typed array, or other iterable
+ * - an object with a length property and indexed values
+ */
 export type Data = Iterable<any> | ArrayLike<any>;
 
 /**
@@ -49,11 +62,69 @@ export type Markish = RenderableMark | RenderFunction | Markish[] | null | undef
 
 /** Shared options for all marks. */
 export interface MarkOptions {
-  // transforms
+  /**
+   * Applies a transform to filter the mark’s index according to the given
+   * channel values; only truthy values are retained. For example, to show only
+   * data whose body mass is greater than 3,000g:
+   *
+   * ```js
+   * filter: (d) => d.body_mass_g > 3000
+   * ```
+   *
+   * Note that filtering only affects the rendered mark index, not the
+   * associated channel values, and thus has no effect on imputed scale domains.
+   */
   filter?: ChannelValue;
+
+  /**
+   * Applies a transform to reverse the order of the mark’s index, say for
+   * reverse input order.
+   */
   reverse?: boolean;
+
+  /**
+   * Either applies a transform to sort the mark’s render index by the specified
+   * channel values, or imputes ordinal scale domains from this mark’s channels.
+   *
+   * When imputing ordinal scale domains from channel values, the **sort**
+   * option is an object whose keys are ordinal scale names such as *x* or *fx*,
+   * and whose values are channel names such as *y*, *y1*, or *y2*. For example,
+   * to impute the *y* scale’s domain from the associated *x* channel values in
+   * ascending order:
+   *
+   * ```js
+   * sort: {y: "x"}
+   * ```
+   *
+   * For different sort options for different scales, replace the channel name
+   * with a *value* object and per-scale options:
+   *
+   * ```js
+   * sort: {y: {value: "x", reverse: true}}
+   * ```
+   *
+   * When sorting the mark’s render index, the **sort** option is instead one
+   * of:
+   *
+   * - a function for comparing data, returning a signed number
+   * - a channel value definition for sorting given values in ascending order
+   * - a {value, order} object for sorting given values
+   * - a {channel, order} object for sorting the named channel’s values
+   *
+   * For example, to render in order of ascending body mass:
+   *
+   * ```js
+   * sort: "body_mass_g"
+   * ```
+   *
+   * See also the Plot.sort transform.
+   */
   sort?: SortOrder | ChannelDomainSort;
+
+  /** A custom mark transform. */
   transform?: TransformFunction;
+
+  /** A custom mark initializer. */
   initializer?: InitializerFunction;
 
   /**