document rule (#1379)

* document rule

* better rules

* edits

* edits

---------

Co-authored-by: Mike Bostock <[email protected]>

Author: Fil

src/marks/rule.d.ts

@@ -3,28 +3,125 @@ import type {InsetOptions} from "../inset.js";
 import type {Interval} from "../interval.js";
 import type {Data, MarkOptions, RenderableMark} from "../mark.js";
 
+/** Options for the ruleX and ruleY marks. */
 interface RuleOptions extends MarkOptions {
+  /**
+   * How to convert a continuous value (**y** for ruleX, or **x** for ruleY)
+   * into an interval; one of:
+   *
+   * - an object that implements *floor*, *offset*, and *range* methods
+   * - a named time interval such as *day* (for date intervals)
+   * - a number (for number intervals), defining intervals at integer multiples of *n*
+   *
+   * For example, to bin Apple’s daily stock price by month, plotting a sequence
+   * of barcodes showing monthly distributions:
+   *
+   * ```js
+   * Plot.ruleY(aapl, {x: "Date", y: "Close", interval: "month"})
+   * ```
+   */
   interval?: Interval;
 }
 
+/** Options for the ruleX mark. */
 export interface RuleXOptions extends RuleOptions, Omit<InsetOptions, "insetLeft" | "insetRight"> {
+  /**
+   * The horizontal position of the tick; an optional channel bound to the *x*
+   * scale. If not specified, the rule will be horizontally centered in the
+   * plot’s frame.
+   */
   x?: ChannelValueSpec;
+
+  /**
+   * Shorthand for specifying both the primary and secondary vertical position
+   * of the tick as the bounds of the containing interval; can only be used in
+   * conjunction with the **interval** option.
+   */
   y?: ChannelValueIntervalSpec;
+
+  /**
+   * The primary (starting) vertical position of the tick; a channel bound to
+   * the *y* scale.
+   *
+   * If *y* represents ordinal values, use a tickX mark instead.
+   */
   y1?: ChannelValueSpec;
+
+  /**
+   * The secondary (ending) vertical position of the tick; a channel bound to
+   * the *y* scale.
+   *
+   * If *y* represents ordinal values, use a tickX mark instead.
+   */
   y2?: ChannelValueSpec;
 }
 
+/** Options for the ruleY mark. */
 export interface RuleYOptions extends RuleOptions, Omit<InsetOptions, "insetTop" | "insetBottom"> {
+  /**
+   * Shorthand for specifying both the primary and secondary horizontal position
+   * of the tick as the bounds of the containing interval; can only be used in
+   * conjunction with the **interval** option.
+   */
   x?: ChannelValueIntervalSpec;
+
+  /**
+   * The primary (starting) horizontal position of the tick; a channel bound to
+   * the *x* scale.
+   *
+   * If *x* represents ordinal values, use a tickY mark instead.
+   */
   x1?: ChannelValueSpec;
+
+  /**
+   * The secondary (ending) horizontal position of the tick; a channel bound to
+   * the *x* scale.
+   *
+   * If *x* represents ordinal values, use a tickY mark instead.
+   */
   x2?: ChannelValueSpec;
+
+  /**
+   * The vertical position of the tick; an optional channel bound to the *y*
+   * scale. If not specified, the rule will be vertically centered in the plot’s
+   * frame.
+   */
   y?: ChannelValueSpec;
 }
 
+/**
+ * Returns a new horizontally-positioned ruleX mark (a vertical line, |) for the
+ * given *data* and *options*. The **x** channel specifies the rule’s horizontal
+ * position and defaults to identity, assuming that *data* = [*x₀*, *x₁*, *x₂*,
+ * …]; the optional **y1** and **y2** channels specify its vertical extent. For
+ * example, for a candlestick chart of Apple’s daily stock price:
+ *
+ * ```js
+ * Plot.ruleX(aapl, {x: "Date", y1: "Open", y2: "Close"})
+ * ```
+ *
+ * If *y* represents ordinal values, use a tickX mark instead.
+ */
 export function ruleX(data?: Data, options?: RuleXOptions): RuleX;
 
+/**
+ * Returns a new vertically-positioned ruleY mark (a horizontal line, —) for the
+ * given *data* and *options*. The **y** channel specifies the vertical position
+ * of the rule and defaults to identity, assuming that *data* = [*y₀*, *y₁*,
+ * *y₂*, …]; the optional **x1** and **x2** channels specify its horizontal
+ * extent. For example, to bin Apple’s daily stock price by month, plotting a
+ * sequence of barcodes showing monthly distributions:
+ *
+ * ```js
+ * Plot.ruleY(aapl, {x: "Date", y: "Close", interval: "month"})
+ * ```
+ *
+ * If *x* represents ordinal values, use a tickY mark instead.
+ */
 export function ruleY(data?: Data, options?: RuleYOptions): RuleY;
 
+/** The ruleX mark. */
 export class RuleX extends RenderableMark {}
 
+/** The ruleY mark. */
 export class RuleY extends RenderableMark {}

src/marks/tick.d.ts

@@ -15,7 +15,7 @@ export interface TickXOptions extends MarkOptions, Omit<InsetOptions, "insetLeft
    * bound to the *y* scale. If not specified, the tick spans the vertical
    * extent of the frame; otherwise the *y* scale must be a *band* scale.
    *
-   * If **y** represents quantitative or temporal values, use a ruleX mark
+   * If *y* represents quantitative or temporal values, use a ruleX mark
    * instead.
    */
   y?: ChannelValueSpec;
@@ -35,7 +35,7 @@ export interface TickYOptions extends MarkOptions, Omit<InsetOptions, "insetTop"
    * horizontal extent of the frame; otherwise the *x* scale must be a *band*
    * scale.
    *
-   * If **x** represents quantitative or temporal values, use a ruleY mark
+   * If *x* represents quantitative or temporal values, use a ruleY mark
    * instead.
    */
   x?: ChannelValueSpec;
@@ -52,8 +52,7 @@ export interface TickYOptions extends MarkOptions, Omit<InsetOptions, "insetTop"
  * Plot.tickX(penguins, {x: "body_mass_g", y: "sex", stroke: "species"})
  * ```
  *
- * If **y** represents quantitative or temporal values, use a ruleX mark
- * instead.
+ * If *y* represents quantitative or temporal values, use a ruleX mark instead.
  */
 export function tickX(data?: Data, options?: TickXOptions): TickX;
 
@@ -62,14 +61,13 @@ export function tickX(data?: Data, options?: TickXOptions): TickX;
  * given *data* and *options*. The **y** channel specifies the vertical position
  * of the tick and defaults to identity, assuming that *data* = [*y₀*, *y₁*,
  * *y₂*, …]; the optional **x** categorical channel specifies its horizontal
- * position. For example, fpr a vertical barcode plot of penguins’ weights:
+ * position. For example, for a vertical barcode plot of penguins’ weights:
  *
  * ```js
  * Plot.tickY(penguins, {y: "body_mass_g", x: "sex", stroke: "species"})
  * ```
  *
- * If **x** represents quantitative or temporal values, use a ruleY mark
- * instead.
+ * If *x* represents quantitative or temporal values, use a ruleY mark instead.
  */
 export function tickY(data?: Data, options?: TickYOptions): TickY;