document density (#1392)

* document density

* lines

src/marks/area.d.ts

@@ -37,9 +37,9 @@ export interface AreaOptions extends MarkOptions, StackOptions, CurveOptions {
   y2?: ChannelValueSpec;
 
   /**
-   * The optional ordinal **z** channel, for grouping data into (possibly
-   * stacked) series to be drawn as separate areas; defaults to **fill** if a
-   * channel, or **stroke** if a channel.
+   * An optional ordinal channel for grouping data into (possibly stacked)
+   * series to be drawn as separate areas; defaults to **fill** if a channel, or
+   * **stroke** if a channel.
    */
   z?: ChannelValue;
 }

src/marks/delaunay.d.ts

@@ -5,9 +5,9 @@ import type {MarkerOptions} from "../marker.js";
 
 /** Options for the Delaunay marks. */
 export interface DelaunayOptions extends MarkOptions, MarkerOptions, CurveOptions {
-  /** A channel for the horizontal position, typically bound to the *x* scale. */
+  /** The horizontal position channel, typically bound to the *x* scale. */
   x?: ChannelValueSpec;
-  /** A channel for the vertical position, typically bound to the *y* scale. */
+  /** The vertical position channel, typically bound to the *y* scale. */
   y?: ChannelValueSpec;
   /** An optional ordinal channel for grouping to produce multiple (possibly overlapping) triangulations. */
   z?: ChannelValue;

src/marks/density.d.ts

@@ -1,15 +1,54 @@
 import type {ChannelValue, ChannelValueSpec} from "../channel.js";
 import type {Data, MarkOptions, RenderableMark} from "../mark.js";
 
+/** Options for the density mark. */
 export interface DensityOptions extends MarkOptions {
+  /** The horizontal position channel, typically bound to the *x* scale. */
   x?: ChannelValueSpec;
+  /** The vertical position channel, typically bound to the *y* scale. */
   y?: ChannelValueSpec;
+
+  /**
+   * An optional ordinal channel for grouping, producing independent contours
+   * for each group. If not specified, it defaults to **fill** if a channel, or
+   * **stroke** if a channel.
+   */
   z?: ChannelValue;
+
+  /**
+   * An optional weight channel specifying the relative contribution of each
+   * point. If not specified, all points have a constant weight of 1.
+   * Non-positive weights are allowed, making associated points repulsive.
+   */
   weight?: ChannelValue;
+
+  /**
+   * The bandwidth, a number in pixels which defaults to 20, specifies the
+   * standard deviation of the Gaussian kernel used for density estimation. A
+   * larger value will produce smoother contours.
+   */
   bandwidth?: number;
+
+  /**
+   * How many contours to produce, and at what density; either a number, by
+   * default 20, specifying one more than the number of contours that will be
+   * computed at uniformly-spaced intervals between 0 (exclusive) and the
+   * maximum density (exclusive); or, an iterable of explicit density values.
+   */
   thresholds?: number | Iterable<number>;
 }
 
+/**
+ * Returns a mark that draws contours representing the estimated density of the
+ * two-dimensional points given by **x** and **y**, and possibly weighted by
+ * **weight**. If either **x** or **y** is not specified, it defaults to the
+ * respective middle of the plot’s frame.
+ *
+ * If the **stroke** or **fill** is specified as *density*, a color channel is
+ * constructed with values representing the density threshold value of each
+ * contour.
+ */
 export function density(data?: Data, options?: DensityOptions): Density;
 
+/** The density mark. */
 export class Density extends RenderableMark {}

src/marks/line.d.ts

@@ -17,9 +17,9 @@ export interface LineOptions extends MarkOptions, MarkerOptions, CurveAutoOption
   y?: ChannelValueSpec;
 
   /**
-   * The optional ordinal **z** channel, for grouping data into (possibly
-   * stacked) series to be drawn as separate lines. If not specified, it
-   * defaults to **fill** if a channel, or **stroke** if a channel.
+   * An optional ordinal channel for grouping data into (possibly stacked)
+   * series to be drawn as separate lines. If not specified, it defaults to
+   * **fill** if a channel, or **stroke** if a channel.
    */
   z?: ChannelValue;
 }