Basic JSDoc types - Plot.plot and all Marks

README.md

@@ -1245,6 +1245,8 @@ The given *options* are passed through to these underlying marks, with the excep
 
 #### Plot.boxX(*data*, *options*)
 
+
+
 ```js
 Plot.boxX(simpsons.map(d => d.imdb_rating))
 ```
@@ -2995,6 +2997,8 @@ passed two node arguments, the child and the parent.
 
 #### Plot.tree(*data*, *options*)
 
+
+
 A convenience compound mark for rendering a tree diagram, including a
 [link](#link) to
 render links from parent to child, an optional

src/marks/area.js

@@ -14,6 +14,11 @@ import {maybeDenseIntervalX, maybeDenseIntervalY} from "../transforms/bin.js";
 import {maybeIdentityX, maybeIdentityY} from "../transforms/identity.js";
 import {maybeStackX, maybeStackY} from "../transforms/stack.js";
 
+/**
+ * @typedef {import("../types.js").Data} Data
+ * @typedef {import("../types.js").MarkOptions} MarkOptions
+ */
+
 const defaults = {
   ariaLabel: "area",
   strokeWidth: 1,
@@ -85,6 +90,8 @@ export class Area extends Mark {
  * [Plot.areaX](https://github.com/observablehq/plot/blob/main/README.md#plotareaxdata-options)
  * is used in the vertical orientation where the baseline and topline share *y*
  * values.
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function area(data, options) {
   if (options === undefined) return areaY(data, {x: first, y: second});
@@ -121,6 +128,8 @@ export function area(data, options) {
  * The **interval** option is recommended to “regularize” sampled data; for
  * example, if your data represents timestamped temperature measurements and you
  * expect one sample per day, use d3.utcDay as the interval.
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function areaX(data, options) {
   const {y = indexOf, ...rest} = maybeDenseIntervalY(options);
@@ -157,6 +166,8 @@ export function areaX(data, options) {
  * The **interval** option is recommended to “regularize” sampled data; for
  * example, if your data represents timestamped temperature measurements and you
  * expect one sample per day, use d3.utcDay as the interval.
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function areaY(data, options) {
   const {x = indexOf, ...rest} = maybeDenseIntervalX(options);

src/marks/arrow.js

@@ -182,6 +182,8 @@ function circleCircleIntersect([ax, ay, ar], [bx, by, br], sign) {
  * ```
  *
  * Returns a new arrow with the given *data* and *options*.
+ * @param {import("../types.js").Data} data
+ * @param {import("../types.js").MarkOptions} options
  */
 export function arrow(data, options = {}) {
   let {x, x1, x2, y, y1, y2, ...remainingOptions} = options;

src/marks/bar.js

@@ -14,6 +14,11 @@ import {maybeIdentityX, maybeIdentityY} from "../transforms/identity.js";
 import {maybeIntervalX, maybeIntervalY} from "../transforms/interval.js";
 import {maybeStackX, maybeStackY} from "../transforms/stack.js";
 
+/**
+ * @typedef {import("../types.js").Data} Data
+ * @typedef {import("../types.js").MarkOptions} MarkOptions
+ */
+
 export class AbstractBar extends Mark {
   constructor(data, channels, options = {}, defaults) {
     super(data, channels, options, defaults);
@@ -163,6 +168,8 @@ export class BarY extends AbstractBar {
  *
  * If the **y** channel is not specified, the bar will span the full vertical
  * extent of the plot (or facet).
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function barX(data, options = {y: indexOf, x2: identity}) {
   return new BarX(data, maybeStackX(maybeIntervalX(maybeIdentityX(options))));
@@ -203,6 +210,8 @@ export function barX(data, options = {y: indexOf, x2: identity}) {
  *
  * If the **x** channel is not specified, the bar will span the full horizontal
  * extent of the plot (or facet).
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function barY(data, options = {x: indexOf, y2: identity}) {
   return new BarY(data, maybeStackY(maybeIntervalY(maybeIdentityY(options))));

src/marks/box.js

@@ -7,6 +7,11 @@ import {dot} from "./dot.js";
 import {ruleX, ruleY} from "./rule.js";
 import {tickX, tickY} from "./tick.js";
 
+/**
+ * @typedef {import("../types.js").Data} Data
+ * @typedef {import("../types.js").MarkOptions} MarkOptions
+ */
+
 /**
  * ```js
  * Plot.boxX(simpsons.map(d => d.imdb_rating))
@@ -16,6 +21,8 @@ import {tickX, tickY} from "./tick.js";
  * defaults to the identity function, as when *data* is an array of numbers. If
  * the **y** option is not specified, it defaults to null; if the **y** option
  * is specified, it should represent an ordinal (discrete) value.
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function boxX(data, options = {}) {
   // Returns a composite mark for producing a horizontal box plot, applying the
@@ -49,6 +56,8 @@ export function boxX(data, options = {}) {
  * defaults to the identity function, as when *data* is an array of numbers. If
  * the **x** option is not specified, it defaults to null; if the **x** option
  * is specified, it should represent an ordinal (discrete) value.
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function boxY(data, options = {}) {
   // Returns a composite mark for producing a vertical box plot, applying the

src/marks/cell.js

@@ -2,6 +2,11 @@ import {identity, indexOf, maybeColorChannel, maybeTuple} from "../options.js";
 import {applyTransform} from "../style.js";
 import {AbstractBar} from "./bar.js";
 
+/**
+ * @typedef {import("../types.js").Data} Data
+ * @typedef {import("../types.js").MarkOptions} MarkOptions
+ */
+
 const defaults = {
   ariaLabel: "cell"
 };
@@ -33,6 +38,8 @@ export class Cell extends AbstractBar {
  * nor **y** options are specified, *data* is assumed to be an array of pairs
  * [[*x₀*, *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …] such that **x** = [*x₀*, *x₁*,
  * *x₂*, …] and **y** = [*y₀*, *y₁*, *y₂*, …].
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function cell(data, options = {}) {
   let {x, y, ...remainingOptions} = options;
@@ -51,6 +58,8 @@ export function cell(data, options = {}) {
  * …], and if the **fill** option is not specified and **stroke** is not a
  * channel, the fill defaults to the identity function and assumes that *data* =
  * [*x₀*, *x₁*, *x₂*, …].
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function cellX(data, options = {}) {
   let {x = indexOf, fill, stroke, ...remainingOptions} = options;
@@ -69,6 +78,8 @@ export function cellX(data, options = {}) {
  * …], and if the **fill** option is not specified and **stroke** is not a
  * channel, the fill defaults to the identity function and assumes that *data* =
  * [*y₀*, *y₁*, *y₂*, …].
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function cellY(data, options = {}) {
   let {y = indexOf, fill, stroke, ...remainingOptions} = options;

src/marks/delaunay.js

@@ -12,6 +12,11 @@ import {
 } from "../style.js";
 import {markers, applyMarkers} from "./marker.js";
 
+/**
+ * @typedef {import("../types.js").Data} Data
+ * @typedef {import("../types.js").MarkOptions} MarkOptions
+ */
+
 const delaunayLinkDefaults = {
   ariaLabel: "delaunay link",
   fill: "none",
@@ -289,6 +294,9 @@ function delaunayMark(DelaunayMark, data, {x, y, ...options} = {}) {
  *
  * If a **z** channel is specified, the input points are grouped by *z*, and
  * separate Delaunay triangulations are constructed for each group.
+ * @param {Data} data
+ * @param {MarkOptions} options
+ * @returns {DelaunayLink}
  */
 export function delaunayLink(data, options) {
   return delaunayMark(DelaunayLink, data, options);
@@ -304,6 +312,9 @@ export function delaunayLink(data, options) {
  *
  * If a **z** channel is specified, the input points are grouped by *z*, and
  * separate Delaunay triangulations are constructed for each group.
+ * @param {Data} data
+ * @param {MarkOptions} options
+ * @returns {DelaunayMesh}
  */
 export function delaunayMesh(data, options) {
   return delaunayMark(DelaunayMesh, data, options);
@@ -320,6 +331,9 @@ export function delaunayMesh(data, options) {
  * separate convex hulls are constructed for each group. If the **z** channel is
  * not specified, it defaults to either the **fill** channel, if any, or the
  * **stroke** channel, if any.
+ * @param {Data} data
+ * @param {MarkOptions} options
+ * @returns {Hull}
  */
 export function hull(data, options) {
   return delaunayMark(Hull, data, options);
@@ -331,6 +345,9 @@ export function hull(data, options) {
  *
  * If a **z** channel is specified, the input points are grouped by *z*, and
  * separate Voronoi tesselations are constructed for each group.
+ * @param {Data} data
+ * @param {MarkOptions} options
+ * @returns {Voronoi}
  */
 export function voronoi(data, options) {
   return delaunayMark(Voronoi, data, options);
@@ -346,6 +363,9 @@ export function voronoi(data, options) {
  *
  * If a **z** channel is specified, the input points are grouped by *z*, and
  * separate Voronoi tesselations are constructed for each group.
+ * @param {Data} data
+ * @param {MarkOptions} options
+ * @returns {VoronoiMesh}
  */
 export function voronoiMesh(data, options) {
   return delaunayMark(VoronoiMesh, data, options);

src/marks/density.js

@@ -12,6 +12,11 @@ import {
 } from "../style.js";
 import {initializer} from "../transforms/basic.js";
 
+/**
+ * @typedef {import("../types.js").Data} Data
+ * @typedef {import("../types.js").MarkOptions} MarkOptions
+ */
+
 const defaults = {
   ariaLabel: "density",
   fill: "none",
@@ -84,6 +89,8 @@ export class Density extends Mark {
  * series. If the **stroke** or **fill** is specified as *density*, a color
  * channel is constructed with values representing the density threshold value
  * of each contour.
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function density(data, options = {}) {
   let {x, y, ...remainingOptions} = options;

src/marks/dot.js

@@ -14,6 +14,11 @@ import {maybeSymbolChannel} from "../symbols.js";
 import {sort} from "../transforms/basic.js";
 import {maybeIntervalMidX, maybeIntervalMidY} from "../transforms/interval.js";
 
+/**
+ * @typedef {import("../types.js").Data} Data
+ * @typedef {import("../types.js").MarkOptions} MarkOptions
+ */
+
 const defaults = {
   ariaLabel: "dot",
   fill: "none",
@@ -122,6 +127,8 @@ export class Dot extends Mark {
  * nor **y** nor **frameAnchor** options are specified, *data* is assumed to be
  * an array of pairs [[*x₀*, *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …] such that
  * **x** = [*x₀*, *x₁*, *x₂*, …] and **y** = [*y₀*, *y₁*, *y₂*, …].
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function dot(data, options = {}) {
   let {x, y, ...remainingOptions} = options;
@@ -143,6 +150,8 @@ export function dot(data, options = {}) {
  * (*interval*.floor(*y*) + *interval*.offset(*interval*.floor(*y*))) / 2. If
  * the interval is specified as a number *n*, *y* will be the midpoint of two
  * consecutive multiples of *n* that bracket *y*.
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function dotX(data, options = {}) {
   const {x = identity, ...remainingOptions} = options;
@@ -163,6 +172,8 @@ export function dotX(data, options = {}) {
  * (*interval*.floor(*x*) + *interval*.offset(*interval*.floor(*x*))) / 2. If
  * the interval is specified as a number *n*, *x* will be the midpoint of two
  * consecutive multiples of *n* that bracket *x*.
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function dotY(data, options = {}) {
   const {y = identity, ...remainingOptions} = options;
@@ -173,6 +184,8 @@ export function dotY(data, options = {}) {
  * Equivalent to
  * [Plot.dot](https://github.com/observablehq/plot/blob/main/README.md#plotdotdata-options)
  * except that the **symbol** option is set to *circle*.
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function circle(data, options) {
   return dot(data, {...options, symbol: "circle"});
@@ -182,6 +195,8 @@ export function circle(data, options) {
  * Equivalent to
  * [Plot.dot](https://github.com/observablehq/plot/blob/main/README.md#plotdotdata-options)
  * except that the **symbol** option is set to *hexagon*.
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function hexagon(data, options) {
   return dot(data, {...options, symbol: "hexagon"});

src/marks/image.js

@@ -118,6 +118,8 @@ export class Image extends Mark {
  * nor **y** nor **frameAnchor** options are specified, *data* is assumed to be
  * an array of pairs [[*x₀*, *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …] such that
  * **x** = [*x₀*, *x₁*, *x₂*, …] and **y** = [*y₀*, *y₁*, *y₂*, …].
+ * @param {import("../types.js").Data} data
+ * @param {import("../types.js").MarkOptions} options
  */
 export function image(data, options = {}) {
   let {x, y, ...remainingOptions} = options;

src/marks/line.js

@@ -13,6 +13,11 @@ import {
 import {maybeDenseIntervalX, maybeDenseIntervalY} from "../transforms/bin.js";
 import {applyGroupedMarkers, markers} from "./marker.js";
 
+/**
+ * @typedef {import("../types.js").Data} Data
+ * @typedef {import("../types.js").MarkOptions} MarkOptions
+ */
+
 const defaults = {
   ariaLabel: "line",
   fill: "none",
@@ -79,6 +84,8 @@ export class Line extends Mark {
  * nor **y** options are specified, *data* is assumed to be an array of pairs
  * [[*x₀*, *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …] such that **x** = [*x₀*, *x₁*,
  * *x₂*, …] and **y** = [*y₀*, *y₁*, *y₂*, …].
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function line(data, options = {}) {
   let {x, y, ...remainingOptions} = options;
@@ -111,6 +118,8 @@ export function line(data, options = {}) {
  * The **interval** option is recommended to “regularize” sampled data; for
  * example, if your data represents timestamped temperature measurements and you
  * expect one sample per day, use d3.utcDay as the interval.
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function lineX(data, options = {}) {
   const {x = identity, y = indexOf, ...remainingOptions} = options;
@@ -142,6 +151,8 @@ export function lineX(data, options = {}) {
  * The **interval** option is recommended to “regularize” sampled data; for
  * example, if your data represents timestamped temperature measurements and you
  * expect one sample per day, use d3.utcDay as the interval.
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function lineY(data, options = {}) {
   const {x = indexOf, y = identity, ...remainingOptions} = options;

src/marks/linearRegression.js

@@ -6,6 +6,11 @@ import {qt} from "../stats.js";
 import {applyDirectStyles, applyGroupedChannelStyles, applyIndirectStyles, applyTransform, groupZ} from "../style.js";
 import {maybeDenseIntervalX, maybeDenseIntervalY} from "../transforms/bin.js";
 
+/**
+ * @typedef {import("../types.js").Data} Data
+ * @typedef {import("../types.js").MarkOptions} MarkOptions
+ */
+
 const defaults = {
   ariaLabel: "linear-regression",
   fill: "currentColor",
@@ -129,6 +134,8 @@ class LinearRegressionY extends LinearRegression {
  *
  * Returns a linear regression mark where *x* is the dependent variable and *y*
  * is the independent variable.
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function linearRegressionX(data, options = {}) {
   const {
@@ -148,6 +155,8 @@ export function linearRegressionX(data, options = {}) {
  *
  * Returns a linear regression mark where *y* is the dependent variable and *x*
  * is the independent variable.
+ * @param {Data} data
+ * @param {MarkOptions} options
  */
 export function linearRegressionY(data, options = {}) {
   const {

src/marks/link.js

@@ -64,6 +64,8 @@ export class Link extends Mark {
  * ```
  *
  * Returns a new link with the given *data* and *options*.
+ * @param {import("../types.js").Data} data
+ * @param {import("../types.js").MarkOptions} options
  */
 export function link(data, options = {}) {
   let {x, x1, x2, y, y1, y2, ...remainingOptions} = options;