Update the descriptions of barThickness, offsetGridLines and offset (#5600)

diff --git a/docs/axes/cartesian/README.md b/docs/axes/cartesian/README.md
index 8518da9f25020de62a12b3f57ff70488041b1bdd..1bf35b79f1694269b8db56e5b70c34280ae039d4 100644 (file)
--- a/docs/axes/cartesian/README.md
+++ b/docs/axes/cartesian/README.md
@@ -15,7 +15,7 @@ All of the included cartesian axes support a number of common options.
 | -----| ---- | --------| -----------
 | `type` | `String` | | Type of scale being employed. Custom scales can be created and registered with a string key. This allows changing the type of an axis for a chart.
 | `position` | `String` | | Position of the axis in the chart. Possible values are: `'top'`, `'left'`, `'bottom'`, `'right'`
-| `offset` | `Boolean` | `false` | If true, extra space is added to the both edges and the axis is scaled to fit into the chart area. This is set to `true` in the bar chart by default.
+| `offset` | `Boolean` | `false` | If true, extra space is added to the both edges and the axis is scaled to fit into the chart area. This is set to `true` for a category scale in a bar chart by default.
 | `id` | `String` | | The ID is used to link datasets and scale axes together. [more...](#axis-id)
 | `gridLines` | `Object` | | Grid line configuration. [more...](../styling.md#grid-line-configuration)
 | `scaleLabel` | `Object` | | Scale title configuration. [more...](../labelling.md#scale-title-configuration)

diff --git a/docs/axes/styling.md b/docs/axes/styling.md
index 0318c9781f80be2d51ffcbb2d361fd4a5eb40c3c..12a170f3e54c080966c766a34229a3468112fa7b 100644 (file)
--- a/docs/axes/styling.md
+++ b/docs/axes/styling.md
@@ -22,7 +22,7 @@ The grid line configuration is nested under the scale configuration in the `grid
 | `zeroLineColor` | Color | `'rgba(0, 0, 0, 0.25)'` | Stroke color of the grid line for the first index (index 0).
 | `zeroLineBorderDash` | `Number[]` | `[]` | Length and spacing of dashes of the grid line for the first index (index 0). See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash)
 | `zeroLineBorderDashOffset` | `Number` | `0` | Offset for line dashes of the grid line for the first index (index 0). See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset)
-| `offsetGridLines` | `Boolean` | `false` | If true, grid lines will be shifted to be between labels. This is set to `true` in the bar chart by default.
+| `offsetGridLines` | `Boolean` | `false` | If true, grid lines will be shifted to be between labels. This is set to `true` for a category scale in a bar chart by default.
 
 ## Tick Configuration
 The tick configuration is nested under the scale configuration in the `ticks` key. It defines options for the tick marks that are generated by the axis.

diff --git a/docs/charts/bar.md b/docs/charts/bar.md
index 84704ba941be69d56e5cf3705b4fd77a977cf902..e4d146b2c67ceade8833e1d6cb7a05b185deaaf6 100644 (file)
--- a/docs/charts/bar.md
+++ b/docs/charts/bar.md
@@ -95,12 +95,19 @@ The bar chart defines the following configuration options. These options are mer
 | ---- | ---- | ------- | -----------
 | `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` | | Manually set width of each bar in pixels. If not set, the base sample widths are calculated automatically so that they take the full available widths without overlap. Then, the bars are sized using `barPercentage` and `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)
 | `maxBarThickness` | `Number` | | Set this to ensure that bars are not sized thicker than this.
 | `gridLines.offsetGridLines` | `Boolean` | `true` | If true, the bars for a particular data point fall between the grid lines. The grid line will move to the left by one half of the tick interval. If false, the grid line will go right down the middle of the bars. [more...](#offsetgridlines)
 
+### barThickness
+If this value is a number, it is applied to the width of each bar, in pixels. When this is enforced, `barPercentage` and `categoryPercentage` are ignored.
+
+If set to `'flex'`, the base sample widths are calculated automatically based on the previous and following samples so that they take the full available widths without overlap. Then, bars are sized using `barPercentage` and `categoryPercentage`. There is no gap when the percentage options are 1. This mode generates bars with different widths when data are not evenly spaced.
+
+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.
+
 ### offsetGridLines
-If true, the bars for a particular data point fall between the grid lines. The grid line will move to the left by one half of the tick interval, which is the space between the grid lines. If false, the grid line will go right down the middle of the bars. This is set to true for a bar chart while false for other charts by default.
+If true, the bars for a particular data point fall between the grid lines. The grid line will move to the left by one half of the tick interval, which is the space between the grid lines. If false, the grid line will go right down the middle of the bars. This is set to true for a category scale in a bar chart while false for other scales or chart types by default.
 
 This setting applies to the axis configuration. If axes are added to the chart, this setting will need to be set for each new axis.