more documentation

docs/marks/bollinger.md

@@ -12,9 +12,9 @@ const k = ref(2);
 
 # Bollinger mark
 
-The **bollinger mark** is a [composite mark](../features/marks.md#marks) consisting of a [line](./line.md) representing a moving average, and an [area](./area.md) representing volatility as a band; the band thickness is proportional to the deviation of nearby values. The bollinger mark is often used to analyze the price of financial instruments such as stocks.
+The **bollinger mark** is a [composite mark](../features/marks.md#marks) consisting of a [line](./line.md) representing a moving average and an [area](./area.md) representing volatility as a band; the band thickness is proportional to the deviation of nearby values. The bollinger mark is often used to analyze the price of financial instruments such as stocks.
 
-For example, the chart below shows the price of Apple stock from 2013–2018, with window size *n* of {{n}} days and radius *k* of {{k}} standard deviations.
+For example, the chart below shows the price of Apple stock from 2013 to 2018, with a window size *n* of {{n}} days and radius *k* of {{k}} standard deviations.
 
 <p>
   <label class="label-input">
@@ -53,18 +53,18 @@ Plot.plot({
 ```
 :::
 
-Or if you want to get *really* fancy… candlesticks!
+Below a candlestick chart is constructed from two [rule marks](./rule.md), with a bollinger mark underneath to emphasize the days when the stock was more volatile.
 
 :::plot
 ```js
 Plot.plot({
-  x: {transform: ((min, max) => (d) => d < min || d >= max ? undefined : d)(new Date("2014-01-01"), new Date("2014-06-01"))},
+  x: {domain: [new Date("2014-01-01"), new Date("2014-06-01")]},
   y: {domain: [68, 92], grid: true},
   color: {domain: [-1, 0, 1], range: ["red", "black", "green"]},
   marks: [
-    Plot.bollingerY(aapl, {x: "Date", y: "Close", stroke: "none"}),
-    Plot.ruleX(aapl, {x: "Date", y1: "Low", y2: "High", strokeWidth: 1}),
-    Plot.ruleX(aapl, {x: "Date", y1: "Open", y2: "Close", strokeWidth: 3, stroke: (d) => Math.sign(d.Close - d.Open)}),
+    Plot.bollingerY(aapl, {x: "Date", y: "Close", stroke: "none", clip: true}),
+    Plot.ruleX(aapl, {x: "Date", y1: "Low", y2: "High", strokeWidth: 1, clip: true}),
+    Plot.ruleX(aapl, {x: "Date", y1: "Open", y2: "Close", strokeWidth: 3, stroke: (d) => Math.sign(d.Close - d.Open), clip: true})
   ]
 })
 ```
@@ -95,17 +95,17 @@ The bollinger mark is a [composite mark](../features/marks.md#marks) consisting
 
 The bollinger mark supports the following special options:
 
-* **n** - the window size (corresponding to the window transform’s **k** option), an integer
-* **k** - the band radius, a number representing a multiple of standard deviations
+* **n** - the window size (the window transform’s **k** option), an integer; defaults to 20
+* **k** - the band radius, a number representing a multiple of standard deviations; defaults to 2
 * **color** - the fill color of the area, and the stroke color of the line; defaults to *currentColor*
 * **opacity** - the fill opacity of the area; defaults to 0.2
 * **fill** - the fill color of the area; defaults to **color**
-* **fillOpacity** - the fill opacity of the area; defaults to **paocity**
+* **fillOpacity** - the fill opacity of the area; defaults to **opacity**
 * **stroke** - the stroke color of the line; defaults to **color**
 * **strokeOpacity** - the stroke opacity of the line; defaults to 1
 * **strokeWidth** - the stroke width of the line in pixels; defaults to 1.5
 
-Any additional options are passed through to the underlying [line mark](./line.md), [area mark](./area.md), and [window transform](../transforms/window.md).
+Any additional options are passed through to the underlying [line mark](./line.md), [area mark](./area.md), and [window transform](../transforms/window.md). Unlike the window transform, the **strict** option defaults to true, and the **anchor** option defaults to *end* (which assumes that the data is in chronological order).
 
 ## bollingerX(*data*, *options*) {#bollingerX}
 
@@ -123,12 +123,10 @@ Plot.bollingerY(aapl, {x: "Date", y: "Close"})
 
 Returns a bollinger mark for when time goes right→ (or ←left). If the **y** option is not specified, it defaults to the identity function, as when *data* is an array of numbers [*y₀*, *y₁*, *y₂*, …]. If the **x** option is not specified, it defaults to [0, 1, 2, …].
 
-TODO Describe the **interval** option inherited from line/area.
-
 ## bollinger(*options*) {#bollinger}
 
 ```js
 Plot.lineY(data, Plot.map({y: Plot.bollinger({n: 20})}, {x: "Date", y: "Close"}))
 ```
 
-Returns a bollinger map method for use with the [map transform](../transforms/map.md).
+Returns a bollinger map method for use with the [map transform](../transforms/map.md). The **k** option here defaults to zero instead of two.

src/marks/bollinger.d.ts

@@ -58,11 +58,36 @@ export type BollingerXOptions = BollingerOptions & AreaXOptions & LineXOptions;
 /** Options for the bollingerY mark. */
 export type BollingerYOptions = BollingerOptions & AreaYOptions & LineYOptions;
 
-/** TODO */
+/**
+ * Returns a new vertically-oriented bollinger mark for the given *data* and
+ * *options*, as in a time-series area chart where time goes up↑ (or down↓).
+ *
+ * If the *x* option is not specified, it defaults to the identity function, as
+ * when data is an array of numbers [*x*₀, *x*₁, *x*₂, …]. If the *y* option is
+ * not specified, it defaults to [0, 1, 2, …].
+ */
 export function bollingerX(data?: Data, options?: BollingerXOptions): CompoundMark;
 
-/** TODO */
+/**
+ * Returns a new horizontally-oriented bollinger mark for the given *data* and
+ * *options*, as in a time-series area chart where time goes right→ (or ←left).
+ *
+ * If the *y* option is not specified, it defaults to the identity function, as
+ * when data is an array of numbers [*y*₀, *y*₁, *y*₂, …]. If the *x* option is
+ * not specified, it defaults to [0, 1, 2, …].
+ */
 export function bollingerY(data?: Data, options?: BollingerYOptions): CompoundMark;
 
-/** TODO */
+/**
+ * Given the specified bollinger *options*, returns a corresponding map
+ * implementation for use with the map transform, allowing the bollinger
+ * transform to be applied to arbitrary channels instead of only *x* and *y*.
+ * For example, to compute the upper volatility band:
+ *
+ * ```js
+ * Plot.map({y: Plot.bollinger({n: 20, k: 2})}, {x: "Date", y: "Close"})
+ * ```
+ *
+ * Here the *k* option defaults to zero instead of two.
+ */
 export function bollinger(options?: BollingerWindowOptions): Map;