Update chart type documentation (#8805)

* Update chart type documentation
* Self-review

diff --git a/docs/charts/bar.md b/docs/charts/bar.md
index d2ea8ba45d6e107832dba8d303a8b8beab3b4e28..d4d0a271fdf85a24d46c585532560e21d40d7171 100644 (file)
--- a/docs/charts/bar.md
+++ b/docs/charts/bar.md
@@ -53,52 +53,77 @@ module.exports = {
 };
 ```
 
-## Example Usage
+## Dataset Properties
 
-```javascript
-var myBarChart = new Chart(ctx, {
-    type: 'bar',
-    data: data,
-    options: options
-});
-```
+Namespaces:
 
-## Dataset Properties
+* `data.datasets[index]` - options for this dataset only
+* `options.datasets.bar` - options for all bar datasets
+* `options.elements.bar` - options for all [bar elements](../configuration/elements.md#bar-configuration)
+* `options` - options for the whole chart
 
 The bar chart allows a number of properties to be specified for each dataset.
 These are used to set display properties for a specific dataset. For example,
 the color of the bars is generally set this way.
+Only the `data` option needs to be specified in the dataset namespace.
 
 | Name | Type | [Scriptable](../general/options.md#scriptable-options) | [Indexable](../general/options.md#indexable-options) | Default
 | ---- | ---- | :----: | :----: | ----
 | [`backgroundColor`](#styling) | [`Color`](../general/colors.md) | Yes | Yes | `'rgba(0, 0, 0, 0.1)'`
 | [`base`](#general) | `number` | Yes | Yes |
+| [`barPercentage`](#barpercentage) | `number` | - | - | `0.9` |
+| [`barThickness`](#barthickness) | `number`\|`string` | - | - | |
 | [`borderColor`](#styling) | [`Color`](../general/colors.md) | Yes | Yes | `'rgba(0, 0, 0, 0.1)'`
 | [`borderSkipped`](#borderskipped) | `string` | Yes | Yes | `'start'`
 | [`borderWidth`](#borderwidth) | `number`\|`object` | Yes | Yes | `0`
 | [`borderRadius`](#borderradius) | `number`\|`object` | Yes | Yes | `0`
-| [`clip`](#general) | `number`\|`object` | - | - | `undefined`
-| [`data`](#data-structure) | `object`\|`object[]`\|`number[]`\|`string[]` | - | - | **required**
-| [`hoverBackgroundColor`](#interactions) | [`Color`](../general/colors.md) | Yes | Yes | `undefined`
-| [`hoverBorderColor`](#interactions) | [`Color`](../general/colors.md) | Yes | Yes | `undefined`
+| [`categoryPercentage`](#categorypercentage) | `number` | - | - | `0.8` |
+| [`clip`](#general) | `number`\|`object` | - | - |
+| [`data`](#data-structure) | `object`\|`object[]`\| `number[]`\|`string[]` | - | - | **required**
+| [`grouped`](#general) | `boolean` | - | - | `true` |
+| [`hoverBackgroundColor`](#interactions) | [`Color`](../general/colors.md) | Yes | Yes |
+| [`hoverBorderColor`](#interactions) | [`Color`](../general/colors.md) | Yes | Yes |
 | [`hoverBorderWidth`](#interactions) | `number` | Yes | Yes | `1`
 | [`hoverBorderRadius`](#interactions) | `number` | Yes | Yes | `0`
 | [`indexAxis`](#general) | `string` | - | - | `'x'`
+| [`maxBarThickness`](#maxbarthickness) | `number` | - | - | |
+| [`minBarLength`](#styling) | `number` | - | - | |
 | [`label`](#general) | `string` | - | - | `''`
 | [`order`](#general) | `number` | - | - | `0`
 | [`pointStyle`](../configuration/elements.md#point-styles) | `string`\|`Image` | Yes | - | `'circle'`
+| [`skipNull`](#general) | `boolean` | - | - | |
+| [`stack`](#general) | `string` | - | - | `'bar'` |
 | [`xAxisID`](#general) | `string` | - | - | first x axis
 | [`yAxisID`](#general) | `string` | - | - | first y axis
 
+All these values, if `undefined`, fallback to the scopes described in [option resolution](../general/options)
+
+### Example dataset configuration
+
+```javascript
+data: {
+    datasets: [{
+        barPercentage: 0.5,
+        barThickness: 6,
+        maxBarThickness: 8,
+        minBarLength: 2,
+        data: [10, 20, 30, 40, 50, 60, 70]
+    }]
+};
+```
+
 ### General
 
 | Name | Description
 | ---- | ----
 | `base` | Base value for the bar in data units along the value axis. If not set, defaults to the value axis base value.
 | `clip` | How to clip relative to chartArea. Positive value allows overflow, negative value clips that many pixels inside chartArea. `0` = clip at chartArea. Clipping can also be configured per side: `clip: {left: 5, top: false, right: -2, bottom: 0}`
+| `grouped` | Should the bars be grouped on index axis. When `true`, all the datasets at same index value will be placed next to each other centering on that index value. When `false`, each bar is placed on its actual index-axis value.
 | `indexAxis` | The base axis of the dataset. `'x'` for vertical bars and `'y'` for horizontal bars.
 | `label` | The label for the dataset which appears in the legend and tooltips.
 | `order` | The drawing order of dataset. Also affects order for stacking, tooltip, and legend.
+| `skipNull` | If `true`, null or undefined values will not be used for spacing calculations when determining bar size.
+| `stack` | The ID of the group to which this dataset belongs to (when stacked, each group will be a separate stack). [more](#stacked-bar-charts)
 | `xAxisID` | The ID of the x-axis to plot this dataset on.
 | `yAxisID` | The ID of the y-axis to plot this dataset on.
 
@@ -113,6 +138,7 @@ The style of each bar can be controlled with the following properties:
 | [`borderSkipped`](#borderskipped) | The edge to skip when drawing bar.
 | [`borderWidth`](#borderwidth) | The bar border width (in pixels).
 | [`borderRadius`](#borderradius) | The bar border radius (in pixels).
+| `minBarLength` | Set this to ensure that bars have a minimum length in pixels.
 | `pointStyle` | Style of the point for legend. [more...](../configuration/elements.md#point-styles)
 
 All these values, if `undefined`, fallback to the associated [`elements.bar.*`](../configuration/elements.md#bar-configuration) options.
@@ -158,33 +184,13 @@ The interaction with each bar can be controlled with the following properties:
 
 All these values, if `undefined`, fallback to the associated [`elements.bar.*`](../configuration/elements.md#bar-configuration) options.
 
-## Dataset Configuration
+### barPercentage
 
-The bar chart accepts the following configuration from the associated dataset options:
+Percent (0-1) of the available width each bar should be within the category width. 1.0 will take the whole category width and put the bars right next to each other. [more...](#barpercentage-vs-categorypercentage)
 
-| Name | Type | Default | Description
-| ---- | ---- | ------- | -----------
-| `barPercentage` | `number` | `0.9` | Percent (0-1) of the available width each bar should be within the category width. 1.0 will take the whole category width and put the bars right next to each other. [more...](#barpercentage-vs-categorypercentage)
-| `categoryPercentage` | `number` | `0.8` | Percent (0-1) of the available width each category should be within the sample width. [more...](#barpercentage-vs-categorypercentage)
-| `barThickness` | `number`\|`string` | | Manually set width of each bar in pixels. If set to `'flex'`, it computes "optimal" sample widths that globally arrange bars side by side. If not set (default), bars are equally sized based on the smallest interval. [more...](#barthickness)
-| `base` | `number` | | Base value for the bar in data units along the value axis. If not set, defaults to the value axis base value.
-| `grouped` | `boolean` | `true` | Should the bars be grouped on index axis. When `true`, all the datasets at same index value will be placed next to each other centering on that index value. When `false`, each bar is placed on its actual index-axis value.
-| `maxBarThickness` | `number` | | Set this to ensure that bars are not sized thicker than this.
-| `minBarLength` | `number` | | Set this to ensure that bars have a minimum length in pixels.
+### categoryPercentage
 
-### Example dataset configuration
-
-```javascript
-data: {
-    datasets: [{
-        barPercentage: 0.5,
-        barThickness: 6,
-        maxBarThickness: 8,
-        minBarLength: 2,
-        data: [10, 20, 30, 40, 50, 60, 70]
-    }]
-};
-```
+Percent (0-1) of the available width each category should be within the sample width. [more...](#barpercentage-vs-categorypercentage)
 
 ### barThickness
 
@@ -194,13 +200,9 @@ If set to `'flex'`, the base sample widths are calculated automatically based on
 
 If not set (default), the base sample widths are calculated using the smallest interval that prevents bar overlapping, and bars are sized using `barPercentage` and `categoryPercentage`. This mode always generates bars equally sized.
 
-## Config Options
+### maxBarThickness
 
-These are the customisation options specific to Bar charts. These options are looked up on access, and form together with the global chart configuration, `Chart.defaults`, the options of the chart.
-
-| Name | Type | Default | Description
-| ---- | ---- | ------- | -----------
-| `skipNull` | `boolean` | `undefined` | If `true`, null or undefined values will not be drawn
+Set this to ensure that bars are not sized thicker than this.
 
 ## Scale Configuration
 
@@ -282,12 +284,6 @@ var stackedBar = new Chart(ctx, {
 });
 ```
 
-The following dataset properties are specific to stacked bar charts.
-
-| Name | Type | Description
-| ---- | ---- | -----------
-| `stack` | `string` | The ID of the group to which this dataset belongs to (when stacked, each group will be a separate stack). Defaults to `bar`.
-
 ## Horizontal Bar Chart
 
 A horizontal bar chart is a variation on a vertical bar chart. It is sometimes used to show trend data, and the comparison of multiple data sets side by side.

diff --git a/docs/charts/bubble.md b/docs/charts/bubble.md
index 94ebbe37ace3c46e8a7e8cfcc0688bbc1c9c39f9..ef29ad2a1c5c728debb9d02c95a5f45f8f9dc46d 100644 (file)
--- a/docs/charts/bubble.md
+++ b/docs/charts/bubble.md
@@ -25,6 +25,7 @@ const data = {
 const config = {
   type: 'bubble',
   data: data,
+  options: {}
 };
 // </block:config>
 
@@ -34,18 +35,14 @@ module.exports = {
 };
 ```
 
-## Example Usage
+## Dataset Properties
 
-```javascript
-// For a bubble chart
-var myBubbleChart = new Chart(ctx, {
-    type: 'bubble',
-    data: data,
-    options: options
-});
-```
+Namespaces:
 
-## Dataset Properties
+* `data.datasets[index]` - options for this dataset only
+* `options.datasets.bubble` - options for all bubble datasets
+* `options.elements.point` - options for all [point elements](../configuration/elements.md#point-configuration)
+* `options` - options for the whole chart
 
 The bubble chart allows a number of properties to be specified for each dataset. These are used to set display properties for a specific dataset. For example, the colour of the bubbles is generally set this way.
 
@@ -67,6 +64,8 @@ The bubble chart allows a number of properties to be specified for each dataset.
 | [`rotation`](#styling) | `number` | Yes | Yes | `0`
 | [`radius`](#styling) | `number` | Yes | Yes | `3`
 
+All these values, if `undefined`, fallback to the scopes described in [option resolution](../general/options)
+
 ### General
 
 | Name | Description

diff --git a/docs/charts/doughnut.md b/docs/charts/doughnut.md
index 66c31125c1573eeec14c3aeedf2332cb8541d6fa..a4f36794f851d34afd0b5e054483c1b8858ec831 100644 (file)
--- a/docs/charts/doughnut.md
+++ b/docs/charts/doughnut.md
@@ -90,6 +90,14 @@ module.exports = {
 
 ## Dataset Properties
 
+Namespaces:
+
+* `data.datasets[index]` - options for this dataset only
+* `options.datasets.doughnut` - options for all doughnut datasets
+* `options.datasets.pie` - options for all pie datasets
+* `options.elements.arc` - options for all [arc elements](../configuration/elements.md#arc-configuration)
+* `options` - options for the whole chart
+
 The doughnut/pie chart allows a number of properties to be specified for each dataset. These are used to set display properties for a specific dataset. For example, the colours of the dataset's arcs are generally set this way.
 
 | Name | Type | [Scriptable](../general/options.md#scriptable-options) | [Indexable](../general/options.md#indexable-options) | Default
@@ -110,6 +118,8 @@ The doughnut/pie chart allows a number of properties to be specified for each da
 | [`rotation`](#general) | `number` | - | - | `undefined`
 | [`weight`](#styling) | `number` | - | - | `1`
 
+All these values, if `undefined`, fallback to the scopes described in [option resolution](../general/options)
+
 ### General
 
 | Name | Description

diff --git a/docs/charts/line.md b/docs/charts/line.md
index f9a687551d5f6c1a6686e8a5471b3cdc858915a4..c04290cab441ee389ba958bd26af860eb22a437e 100644 (file)
--- a/docs/charts/line.md
+++ b/docs/charts/line.md
@@ -30,17 +30,15 @@ module.exports = {
 };
 ```
 
-## Example Usage
+## Dataset Properties
 
-```javascript
-var myLineChart = new Chart(ctx, {
-    type: 'line',
-    data: data,
-    options: options
-});
-```
+Namespaces:
 
-## Dataset Properties
+* `data.datasets[index]` - options for this dataset only
+* `options.datasets.line` - options for all line datasets
+* `options.elements.line` - options for all [line elements](../configuration/elements.md#line-configuration)
+* `options.elements.point` - options for all [point elements](../configuration/elements.md#point-configuration)
+* `options` - options for the whole chart
 
 The line chart allows a number of properties to be specified for each dataset. These are used to set display properties for a specific dataset. For example, the colour of a line is generally set this way.
 
@@ -54,7 +52,7 @@ The line chart allows a number of properties to be specified for each dataset. T
 | [`borderJoinStyle`](#line-styling) | `string` | Yes | - | `'miter'`
 | [`borderWidth`](#line-styling) | `number` | Yes | - | `3`
 | [`clip`](#general) | `number`\|`object` | - | - | `undefined`
-| [`data`](#data-structure) | `object`\|`object[]`\|`number[]`\|`string[]` | - | - | **required**
+| [`data`](#data-structure) | `object`\|`object[]`\| `number[]`\|`string[]` | - | - | **required**
 | [`cubicInterpolationMode`](#cubicinterpolationmode) | `string` | Yes | - | `'default'`
 | [`fill`](#line-styling) | `boolean`\|`string` | Yes | - | `false`
 | [`hoverBackgroundColor`](#line-styling) | [`Color`](../general/colors.md) | Yes | - | `undefined`
@@ -81,10 +79,13 @@ The line chart allows a number of properties to be specified for each dataset. T
 | [`pointStyle`](#point-styling) | `string`\|`Image` | Yes | Yes | `'circle'`
 | [`showLine`](#line-styling) | `boolean` | - | - | `true`
 | [`spanGaps`](#line-styling) | `boolean`\|`number` | - | - | `undefined`
+| [`stack`](#general) | `string` | - | - | `'line'` |
 | [`stepped`](#stepped) | `boolean`\|`string` | - | - | `false`
 | [`xAxisID`](#general) | `string` | - | - | first x axis
 | [`yAxisID`](#general) | `string` | - | - | first y axis
 
+All these values, if `undefined`, fallback to the scopes described in [option resolution](../general/options)
+
 ### General
 
 | Name | Description
@@ -93,6 +94,7 @@ The line chart allows a number of properties to be specified for each dataset. T
 | `indexAxis` | The base axis of the dataset. `'x'` for horizontal lines and `'y'` for vertical lines.
 | `label` | The label for the dataset which appears in the legend and tooltips.
 | `order` | The drawing order of dataset. Also affects order for stacking, tooltip, and legend.
+| `stack` | The ID of the group to which this dataset belongs to (when stacked, each group will be a separate stack). [more](#stacked-area-charts)
 | `xAxisID` | The ID of the x-axis to plot this dataset on.
 | `yAxisID` | The ID of the y-axis to plot this dataset on.
 
@@ -168,15 +170,6 @@ The following values are supported for `stepped`.
 
 If the `stepped` value is set to anything other than false, `tension` will be ignored.
 
-## Configuration Options
-
-The line chart defines the following configuration options. These options are looked up on access, and form together with the global chart configuration, `Chart.defaults`, the options of the chart.
-
-| Name | Type | Default | Description
-| ---- | ---- | ------- | -----------
-| `showLine` | `boolean` | `true` | If false, the lines between points are not drawn.
-| `spanGaps` | `boolean`\|`number` | `false` | If true, lines will be drawn between points with no or null data. If false, points with `null` data will create a break in the line. Can also be a number specifying the maximum gap length to span. The unit of the value depends on the scale used.
-
 ## Default Options
 
 It is common to want to apply a configuration setting to all created line charts. The global line chart settings are stored in `Chart.overrides.line`. Changing the global options only affects charts created after the change. Existing charts are not changed.
@@ -269,18 +262,6 @@ module.exports = {
 };
 ```
 
-## Example
-
-```javascript
-var myLineChart = new Chart(ctx, {
-    type: 'line',
-    data: data,
-    options: {
-      indexAxis: 'y'
-    }
-});
-```
-
 ### Config Options
 
 The configuration options for the vertical line chart are the same as for the [line chart](#configuration-options). However, any options specified on the x-axis in a line chart, are applied to the y-axis in a vertical line chart.

diff --git a/docs/charts/polar.md b/docs/charts/polar.md
index cf41a1a25312734ec34448d3ad0e0e9a57ffb997..550674272d23ed6166f5b1c91ca306ff8549a96e 100644 (file)
--- a/docs/charts/polar.md
+++ b/docs/charts/polar.md
@@ -32,6 +32,7 @@ const data = {
 const config = {
   type: 'polarArea',
   data: data,
+  options: {}
 };
 // </block:config>
 
@@ -41,17 +42,14 @@ module.exports = {
 };
 ```
 
-## Example Usage
+## Dataset Properties
 
-```javascript
-new Chart(ctx, {
-    data: data,
-    type: 'polarArea',
-    options: options
-});
-```
+Namespaces:
 
-## Dataset Properties
+* `data.datasets[index]` - options for this dataset only
+* `options.datasets.polarArea` - options for all polarArea datasets
+* `options.elements.arc` - options for all [arc elements](../configuration/elements.md#arc-configuration)
+* `options` - options for the whole chart
 
 The following options can be included in a polar area chart dataset to configure options for that specific dataset.
 
@@ -67,6 +65,8 @@ The following options can be included in a polar area chart dataset to configure
 | [`hoverBorderColor`](#interactions) | [`Color`](../general/colors.md) | Yes | Yes | `undefined`
 | [`hoverBorderWidth`](#interactions) | `number` | Yes | Yes | `undefined`
 
+All these values, if `undefined`, fallback to the scopes described in [option resolution](../general/options)
+
 ### General
 
 | Name | Description

diff --git a/docs/charts/radar.md b/docs/charts/radar.md
index fe2d7427abbffc953719cbf426b91caf072b8bc5..8aecced8945dca0eb6da2dc4186837ba01293185 100644 (file)
--- a/docs/charts/radar.md
+++ b/docs/charts/radar.md
@@ -60,19 +60,15 @@ module.exports = {
 };
 ```
 
-<ExampleChart/>
+## Dataset Properties
 
-## Example Usage
+Namespaces:
 
-```javascript
-var myRadarChart = new Chart(ctx, {
-    type: 'radar',
-    data: data,
-    options: options
-});
-```
-
-## Dataset Properties
+* `data.datasets[index]` - options for this dataset only
+* `options.datasets.line` - options for all line datasets
+* `options.elements.line` - options for all [line elements](../configuration/elements.md#line-configuration)
+* `options.elements.point` - options for all [point elements](../configuration/elements.md#point-configuration)
+* `options` - options for the whole chart
 
 The radar chart allows a number of properties to be specified for each dataset. These are used to set display properties for a specific dataset. For example, the colour of a line is generally set this way.
 
@@ -111,6 +107,8 @@ The radar chart allows a number of properties to be specified for each dataset.
 | [`pointStyle`](#point-styling) | `string`\|`Image` | Yes | Yes | `'circle'`
 | [`spanGaps`](#line-styling) | `boolean` | - | - | `undefined`
 
+All these values, if `undefined`, fallback to the scopes described in [option resolution](../general/options)
+
 ### General
 
 | Name | Description
@@ -165,14 +163,6 @@ The interaction with each point can be controlled with the following properties:
 | `pointHoverBorderWidth` | Border width of point when hovered.
 | `pointHoverRadius` | The radius of the point when hovered.
 
-## Configuration Options
-
-The radar chart defines the following configuration options. These options are looked up on access, and form together with the global chart configuration, `Chart.defaults`, the options of the chart.
-
-| Name | Type | Default | Description
-| ---- | ---- | ------- | -----------
-| `spanGaps` | `boolean` | `false` | If false, `null` data causes a break in the line.
-
 ## Scale Options
 
 The radar chart supports only a single scale. The options for this scale are defined in the `scale` property.

diff --git a/docs/charts/scatter.md b/docs/charts/scatter.md
index 918995d8d361b3bda2905aaec9b3be0fd4e28954..1c2462f4bcbc7d0a1b6a7d2b09c3448e45c4f5e4 100644 (file)
--- a/docs/charts/scatter.md
+++ b/docs/charts/scatter.md
@@ -48,6 +48,14 @@ module.exports = {
 
 ## Dataset Properties
 
+Namespaces:
+
+* `data.datasets[index]` - options for this dataset only
+* `options.datasets.scatter` - options for all scatter datasets
+* `options.elements.line` - options for all [line elements](../configuration/elements.md#line-configuration)
+* `options.elements.point` - options for all [point elements](../configuration/elements.md#point-configuration)
+* `options` - options for the whole chart
+
 The scatter chart supports all of the same properties as the [line chart](./charts/line.md#dataset-properties).
 By default, the scatter chart will override the showLine property of the line chart to `false`.