document barX barY (#1397)

* document barX barY

* Update src/marks/bar.d.ts

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

* prettier

* edits

* edits

* edits, and a bit more repetition

* fix typos

---------

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

Author: Fil

src/marks/area.d.ts

@@ -136,12 +136,23 @@ export function area(data?: Data, options?: AreaOptions): Area;
 /**
  * Returns a new vertically-oriented area for the given *data* and *options*,
  * where the baseline and topline share **y** values, as in a time-series area
- * chart where time goes up↑.
+ * chart where time goes up↑. For example, to plot Apple’s daily stock price:
  *
  * ```js
  * Plot.areaX(aapl, {y: "Date", x: "Close"})
  * ```
  *
+ * If neither **x1** nor **x2** is specified, an implicit stackX transform is
+ * applied and **x** defaults to the identity function, assuming that *data* =
+ * [*x₀*, *x₁*, *x₂*, …]. Otherwise, if only one of **x1** or **x2** is
+ * specified, the other defaults to **x**, which defaults to zero.
+ *
+ * If an **interval** is specified, **y** values are binned accordingly,
+ * allowing zeroes for empty bins instead of interpolating across gaps. This is
+ * recommended to “regularize” sampled data; for example, if your data
+ * represents timestamped observations and you expect one observation per day,
+ * use *day* as the **interval**.
+ *
  * Variable aesthetic channels are supported: if the **fill** is defined as a
  * channel, the area will be broken into contiguous overlapping sections when
  * the fill color changes; the fill color will apply to the interval spanning
@@ -156,12 +167,23 @@ export function areaX(data?: Data, options?: AreaXOptions): Area;
 /**
  * Returns a new horizontally-oriented area for the given *data* and *options*,
  * where the baseline and topline share **x** values, as in a time-series area
- * chart where time goes right→.
+ * chart where time goes right→. For example, to plot Apple’s daily stock price:
  *
  * ```js
  * Plot.areaY(aapl, {x: "Date", y: "Close"})
  * ```
  *
+ * If neither **y1** nor **y2** is specified, an implicit stackY transform is
+ * applied and **y** defaults to the identity function, assuming that *data* =
+ * [*y₀*, *y₁*, *y₂*, …]. Otherwise, if only one of **y1** or **y2** is
+ * specified, the other defaults to **y**, which defaults to zero.
+ *
+ * If an **interval** is specified, **x** values are binned accordingly,
+ * allowing zeroes for empty bins instead of interpolating across gaps. This
+ * is recommended to “regularize” sampled data; for example, if your data
+ * represents timestamped observations and you expect one observation per day,
+ * use *day* as the **interval**.
+ *
  * Variable aesthetic channels are supported: if the **fill** is defined as a
  * channel, the area will be broken into contiguous overlapping sections when
  * the fill color changes; the fill color will apply to the interval spanning

src/marks/bar.d.ts

@@ -4,30 +4,211 @@ import type {InsetOptions} from "../inset.js";
 import type {Data, MarkOptions, RenderableMark} from "../mark.js";
 import type {StackOptions} from "../transforms/stack.js";
 
+/** Options for the barX and barY marks. */
 interface BarOptions extends MarkOptions, InsetOptions, StackOptions {
-  interval?: Interval;
+  /**
+   * The rounded corner [*x*-radius][1], either in pixels or as a percentage of
+   * the bar width. If **rx** is not specified, it defaults to **ry** if
+   * present, and otherwise draws square corners.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/rx
+   */
   rx?: number | string;
+
+  /**
+   * The rounded corner [*y*-radius][1], either in pixels or as a percentage of
+   * the bar height. If **ry** is not specified, it defaults to **rx** if
+   * present, and otherwise draws square corners.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/ry
+   */
   ry?: number | string;
+
+  /**
+   * How to convert a continuous value (**x** for barX, or **y** for barY) into
+   * an interval (**x1** and **x2** for barX, or **y1** and **y2** for barY);
+   * 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, for a scatterplot showing the frequency distribution of
+   * English letters, where the vertical extent of each bar covers a unit
+   * percentage:
+   *
+   * ```js
+   * Plot.barY(alphabet, {x: "letter", y: "frequency", interval: 0.01})
+   * ```
+   *
+   * Setting this option disables the implicit stack transform (stackX or barX,
+   * or stackY for barY).
+   */
+  interval?: Interval;
 }
 
+/** Options for the barX mark. */
 export interface BarXOptions extends BarOptions {
+  /**
+   * The horizontal position (or length/width) channel, typically bound to the
+   * *x* scale.
+   *
+   * If neither **x1** nor **x2** nor **interval** is specified, an implicit
+   * stackX transform is applied and **x** defaults to the identity function,
+   * assuming that *data* = [*x₀*, *x₁*, *x₂*, …]. Otherwise if an **interval**
+   * is specified, then **x1** and **x2** are derived from **x**, representing
+   * the lower and upper bound of the containing interval, respectively.
+   * Otherwise, if only one of **x1** or **x2** is specified, the other defaults
+   * to **x**, which defaults to zero.
+   */
   x?: ChannelValueIntervalSpec;
+
+  /**
+   * The required primary (starting) horizontal position channel, typically
+   * bound to the *x* scale. Setting this option disables the implicit stackX
+   * transform.
+   */
   x1?: ChannelValueSpec;
+
+  /**
+   * The required secondary (ending) horizontal position channel, typically
+   * bound to the *x* scale. Setting this option disables the implicit stackX
+   * transform.
+   */
   x2?: ChannelValueSpec;
+
+  /**
+   * The optional vertical position of the bar; a categorical channel typically
+   * bound to the *y* scale. If not specified, the bar 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 rectX mark
+   * instead.
+   */
   y?: ChannelValueSpec;
 }
 
+/** Options for the barY mark. */
 export interface BarYOptions extends BarOptions {
+  /**
+   * The vertical position (or length/height) channel, typically bound to the
+   * *y* scale.
+   *
+   * If neither **y1** nor **y2** nor **interval** is specified, an implicit
+   * stackY transform is applied and **y** defaults to the identity function,
+   * assuming that *data* = [*y₀*, *y₁*, *y₂*, …]. Otherwise if an **interval**
+   * is specified, then **y1** and **y2** are derived from **y**, representing
+   * the lower and upper bound of the containing interval, respectively.
+   * Otherwise, if only one of **y1** or **y2** is specified, the other defaults
+   * to **y**, which defaults to zero.
+   */
   y?: ChannelValueIntervalSpec;
+
+  /**
+   * The required primary (starting) vertical position channel, typically bound
+   * to the *y* scale. Setting this option disables the implicit stackY
+   * transform.
+   */
   y1?: ChannelValueSpec;
+
+  /**
+   * The required secondary (ending) horizontal position channel, typically
+   * bound to the *y* scale. Setting this option disables the implicit stackY
+   * transform.
+   */
   y2?: ChannelValueSpec;
+
+  /**
+   * The optional horizontal position of the bar; a categorical channel
+   * typically bound to the *x* scale. If not specified, the bar spans the
+   * horizontal extent of the frame; otherwise the *x* scale must be a *band*
+   * scale.
+   *
+   * If *x* represents quantitative or temporal values, use a rectY mark
+   * instead.
+   */
   x?: ChannelValueSpec;
 }
 
+/**
+ * Returns a new horizontal bar mark for the given *data* and *options*; the
+ * required *x* values must be quantitative, and the optional *y* values must be
+ * ordinal. For example, for a horizontal bar chart of English letter frequency:
+ *
+ * ```js
+ * Plot.barX(alphabet, {x: "frequency", y: "letter"})
+ * ```
+ *
+ * If neither **x1** nor **x2** nor **interval** is specified, an implicit
+ * stackX transform is applied and **x** defaults to the identity function,
+ * assuming that *data* = [*x₀*, *x₁*, *x₂*, …]. Otherwise if an **interval** is
+ * specified, then **x1** and **x2** are derived from **x**, representing the
+ * lower and upper bound of the containing interval, respectively. Otherwise, if
+ * only one of **x1** or **x2** is specified, the other defaults to **x**, which
+ * defaults to zero.
+ *
+ * The optional **y** ordinal channel specifies the vertical position; it is
+ * typically bound to the *y* scale, which must be a *band* scale. If the **y**
+ * channel is not specified, the bar will span the vertical extent of the plot’s
+ * frame. The barX mark is often used in conjunction with the groupY transform.
+ * For a stacked histogram of penguins by species, colored by sex:
+ *
+ * ```js
+ * Plot.barX(penguins, Plot.groupY({x: "count"}, {y: "species", fill: "sex"}))
+ * ```
+ *
+ * If *y* is quantitative, use the rectX mark instead, possibly with a binY
+ * transform.
+ *
+ * If *options* is undefined, then **y** defaults to the zero-based index of
+ * *data* [0, 1, 2, …], allowing a quick bar chart from an array of numbers:
+ *
+ * ```js
+ * Plot.barX([4, 9, 24, 46, 66, 7])
+ * ```
+ */
 export function barX(data?: Data, options?: BarXOptions): BarX;
 
+/**
+ * Returns a new vertical bar mark for the given *data* and *options*; the
+ * required *y* values must be quantitative, and the optional *x* values must be
+ * ordinal. For example, for a vertical bar chart of English letter frequency:
+ *
+ * ```js
+ * Plot.barY(alphabet, {y: "frequency", x: "letter"})
+ * ```
+ * If neither **y1** nor **y2** nor **interval** is specified, an implicit
+ * stackY transform is applied and **y** defaults to the identity function,
+ * assuming that *data* = [*y₀*, *y₁*, *y₂*, …]. Otherwise if an **interval** is
+ * specified, then **y1** and **y2** are derived from **y**, representing the
+ * lower and upper bound of the containing interval, respectively. Otherwise, if
+ * only one of **y1** or **y2** is specified, the other defaults to **y**, which
+ * defaults to zero.
+ *
+ * The optional **x** ordinal channel specifies the horizontal position; it is
+ * typically bound to the *x* scale, which must be a *band* scale. If the **x**
+ * channel is not specified, the bar will span the horizontal extent of the
+ * plot’s frame. The barY mark is often used in conjunction with the groupX
+ * transform. For a stacked histogram of penguins by species, colored by sex:
+ *
+ * ```js
+ * Plot.barY(penguins, Plot.groupX({y: "count"}, {x: "species", fill: "sex"}))
+ * ```
+ *
+ * If *x* is quantitative, use the rectY mark instead, possibly with a binX
+ * transform.
+ *
+ * If *options* is undefined, then **x** defaults to the zero-based index of
+ * *data* [0, 1, 2, …], allowing a quick bar chart from an array of numbers:
+ *
+ * ```js
+ * Plot.barY([4, 9, 24, 46, 66, 7])
+ * ```
+ */
 export function barY(data?: Data, options?: BarYOptions): BarY;
 
+/** The barX mark. */
 export class BarX extends RenderableMark {}
 
+/** The barY mark. */
 export class BarY extends RenderableMark {}

src/marks/frame.d.ts

@@ -20,7 +20,7 @@ export interface FrameOptions extends MarkOptions, InsetOptions {
   rx?: number | string;
 
   /**
-   * The rounded corner [*y*-radius[1], either in pixels or as a percentage of
+   * The rounded corner [*y*-radius][1], either in pixels or as a percentage of
    * the frame height. If **ry** is not specified, it defaults to **rx** if
    * present, and otherwise draws square corners.
    *

src/marks/rule.d.ts

@@ -7,7 +7,8 @@ import type {Data, MarkOptions, RenderableMark} from "../mark.js";
 interface RuleOptions extends MarkOptions {
   /**
    * How to convert a continuous value (**y** for ruleX, or **x** for ruleY)
-   * into an interval; one of:
+   * into an interval (**y1** and **y2** for ruleX, or **x1** and **x2** for
+   * ruleY); one of:
    *
    * - an object that implements *floor*, *offset*, and *range* methods
    * - a named time interval such as *day* (for date intervals)
@@ -100,6 +101,13 @@ export interface RuleYOptions extends RuleOptions, Omit<InsetOptions, "insetTop"
  * Plot.ruleX(aapl, {x: "Date", y1: "Open", y2: "Close"})
  * ```
  *
+ * The ruleX mark is often used to highlight specific *x* values. For example,
+ * to draw a rule at *x* = 0:
+ *
+ * ```js
+ * Plot.ruleX([0])
+ * ```
+ *
  * If *y* represents ordinal values, use a tickX mark instead.
  */
 export function ruleX(data?: Data, options?: RuleXOptions): RuleX;
@@ -116,6 +124,13 @@ export function ruleX(data?: Data, options?: RuleXOptions): RuleX;
  * Plot.ruleY(aapl, {x: "Date", y: "Close", interval: "month"})
  * ```
  *
+ * The ruleY mark is often used to highlight specific *y* values. For example,
+ * to draw a rule at *y* = 0:
+ *
+ * ```js
+ * Plot.ruleY([0])
+ * ```
+ *
  * If *x* represents ordinal values, use a tickY mark instead.
  */
 export function ruleY(data?: Data, options?: RuleYOptions): RuleY;