Update chart type documentation (#8805)

* Update chart type documentation * Self-review
chartjs · Apr 3, 2021 · 33df3a6 · 33df3a6
1 parent 0192334
commit 33df3a6
Show file tree

Hide file tree

Showing 7 changed files with 102 additions and 118 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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