Skip to content

Commit d169f3e

Browse files
web-padawanweb-padawan
authored
docs: improve code examples in charts JSDoc annotations (#9964)
1 parent c2b284d commit d169f3e

File tree

4 files changed

+108
-152
lines changed

4 files changed

+108
-152
lines changed

‎packages/charts/src/vaadin-chart-series.d.ts‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,15 @@ export * from './vaadin-chart-series-mixin.js';
1919
* To use `<vaadin-chart-series>`, add it inside a `<vaadin-chart>` element:
2020
*
2121
* ```html
22-
* <vaadin-chart>
23-
* <vaadin-chart-series></vaadin-chart-series>
24-
* </vaadin-chart>
22+
* <vaadin-chart>
23+
* <vaadin-chart-series></vaadin-chart-series>
24+
* </vaadin-chart>
2525
* ```
2626
*
2727
* `<vaadin-chart-series>` accepts `values` as an array attribute, so you can add it to your element definition:
2828
*
2929
* ```html
30-
* <vaadin-chart-series values="[10,20,30,40,50]"></vaadin-chart-series>
30+
* <vaadin-chart-series values="[10, 20, 30, 40, 50]"></vaadin-chart-series>
3131
* ```
3232
*
3333
* which will add a new line series, where each value will be a data point.
@@ -40,18 +40,18 @@ export * from './vaadin-chart-series-mixin.js';
4040
* To create a new series, call `document.createElement('vaadin-chart-series')` and append it to your `<vaadin-chart>`:
4141
*
4242
* ```js
43-
* const chart = \* a <vaadin-chart> reference *\
44-
* const newSeries = document.createElement('vaadin-chart-series');
45-
* newSeries.values = [10,20,30,40,50];
46-
* chart.appendChild(newSeries);
43+
* const chart = document.querySelector('vaadin-chart');
44+
* const newSeries = document.createElement('vaadin-chart-series');
45+
* newSeries.values = [10, 20, 30, 40, 50];
46+
* chart.appendChild(newSeries);
4747
* ```
4848
*
4949
* In order to remove it, you should use the series to be removed as a reference for the `#removeChild()` call:
5050
*
5151
* ```js
52-
* const chart = \* a <vaadin-chart> reference *\
53-
* const seriesToBeRemoved = \* a <vaadin-chart-series> reference to remove*\
54-
* chart.removeChild(seriesToBeRemoved);
52+
* const chart = document.querySelector('vaadin-chart');
53+
* const seriesToBeRemoved = chart.querySelector('vaadin-chart-series');
54+
* chart.removeChild(seriesToBeRemoved);
5555
* ```
5656
*/
5757
declare class ChartSeries extends ChartSeriesMixin(HTMLElement) {}

‎packages/charts/src/vaadin-chart-series.js‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -21,15 +21,15 @@ import { ChartSeriesMixin } from './vaadin-chart-series-mixin.js';
2121
* To use `<vaadin-chart-series>`, add it inside a `<vaadin-chart>` element:
2222
*
2323
* ```html
24-
* <vaadin-chart>
25-
* <vaadin-chart-series></vaadin-chart-series>
26-
* </vaadin-chart>
24+
* <vaadin-chart>
25+
* <vaadin-chart-series></vaadin-chart-series>
26+
* </vaadin-chart>
2727
* ```
2828
*
2929
* `<vaadin-chart-series>` accepts `values` as an array attribute, so you can add it to your element definition:
3030
*
3131
* ```html
32-
* <vaadin-chart-series values="[10,20,30,40,50]"></vaadin-chart-series>
32+
* <vaadin-chart-series values="[10, 20, 30, 40, 50]"></vaadin-chart-series>
3333
* ```
3434
*
3535
* which will add a new line series, where each value will be a data point.
@@ -42,18 +42,18 @@ import { ChartSeriesMixin } from './vaadin-chart-series-mixin.js';
4242
* To create a new series, call `document.createElement('vaadin-chart-series')` and append it to your `<vaadin-chart>`:
4343
*
4444
* ```js
45-
* const chart = \* a <vaadin-chart> reference *\
46-
* const newSeries = document.createElement('vaadin-chart-series');
47-
* newSeries.values = [10,20,30,40,50];
48-
* chart.appendChild(newSeries);
45+
* const chart = document.querySelector('vaadin-chart');
46+
* const newSeries = document.createElement('vaadin-chart-series');
47+
* newSeries.values = [10, 20, 30, 40, 50];
48+
* chart.appendChild(newSeries);
4949
* ```
5050
*
5151
* In order to remove it, you should use the series to be removed as a reference for the `#removeChild()` call:
5252
*
5353
* ```js
54-
* const chart = \* a <vaadin-chart> reference *\
55-
* const seriesToBeRemoved = \* a <vaadin-chart-series> reference to remove*\
56-
* chart.removeChild(seriesToBeRemoved);
54+
* const chart = document.querySelector('vaadin-chart');
55+
* const seriesToBeRemoved = chart.querySelector('vaadin-chart-series');
56+
* chart.removeChild(seriesToBeRemoved);
5757
* ```
5858
*
5959
* @customElement

‎packages/charts/src/vaadin-chart.d.ts‎

Lines changed: 43 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -21,89 +21,67 @@ export * from './vaadin-chart-mixin.js';
2121
* There are two ways of configuring your `<vaadin-chart>` element: **HTML API**, **JS API** and **JSON API**.
2222
* Note that you can make use of all APIs in your element.
2323
*
24-
* #### Configuring your chart using HTML API
24+
* #### Using HTML API
2525
*
2626
* `vaadin-chart` has a set of attributes to make it easier for you to customize your chart.
2727
*
2828
* ```html
29-
* <vaadin-chart title="The chart title" subtitle="The chart subtitle">
30-
* <vaadin-chart-series
31-
* type="column"
32-
* title="The series title"
33-
* values="[10,20,30]">
34-
* </vaadin-chart-series>
35-
* </vaadin-chart>
29+
* <vaadin-chart title="The chart title" subtitle="The chart subtitle">
30+
* <vaadin-chart-series
31+
* type="column"
32+
* title="The series title"
33+
* values="[10, 20, 30]"
34+
* ></vaadin-chart-series>
35+
* </vaadin-chart>
3636
* ```
3737
*
3838
* > Note that while you can set type for each series individually, for some types, such as `'bar'`, `'gauge'` and `'solidgauge'`, you
3939
* > have to set it as the default series type on `<vaadin-chart>` in order to work properly.
4040
*
41-
* #### Configuring your chart using JS API
41+
* #### Using JS API
42+
*
43+
* Use [`configuration`](#/elements/vaadin-chart#property-configuration) property to set chart title, categories and data:
4244
*
43-
* 1. Set an id for the `<vaadin-chart>` in the template
44-
* ```html
45-
* <vaadin-chart id="mychart"></vaadin-chart>
46-
* ```
47-
* 1. Add a function that uses `configuration` property (JS Api) to set chart title, categories and data
48-
* ```js
49-
* initChartWithJSApi() {
50-
* requestAnimationFrame(() => {
51-
* const configuration = this.$.mychart.configuration;
52-
* configuration.setTitle({ text: 'The chart title' });
53-
* // By default there is one X axis, it is referenced by configuration.xAxis[0].
54-
* configuration.xAxis[0].setCategories(['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']);
55-
* configuration.addSeries({
56-
* type: 'column',
57-
* data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]
58-
* });
59-
* });
60-
* }
61-
* ```
62-
* 1. Call that function from connectedCallback (when the element is added to a document)
6345
* ```js
64-
* connectedCallback() {
65-
* super.connectedCallback();
66-
* this.initChartWithJSApi();
67-
* }
46+
* const chart = document.querySelector('vaadin-chart');
47+
*
48+
* // Wait for default configuration to be ready
49+
* requestAnimationFrame(() => {
50+
* const configuration = chart.configuration;
51+
* configuration.setTitle({ text: 'The chart title' });
52+
* // By default there is one X axis, it is referenced by configuration.xAxis[0].
53+
* configuration.xAxis[0].setCategories(['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']);
54+
* configuration.addSeries({
55+
* type: 'column',
56+
* data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]
57+
* });
58+
* });
6859
* ```
6960
*
70-
* #### Configuring your chart using JS JSON API
61+
* #### Using JS JSON API
7162
*
72-
* JS JSON API is a simple alternative to the JS API.
63+
* Use [`updateConfiguration`](#/elements/vaadin-chart#method-updateConfiguration) method to set chart title, categories and data:
7364
*
74-
* 1. Set an id for the `<vaadin-chart>` in the template
75-
* ```html
76-
* <vaadin-chart id="mychart"></vaadin-chart>
77-
* ```
78-
* 1. Add a function that uses `updateConfiguration` method (JS JSON Api) to set chart title, categories and data
79-
* ```js
80-
* initChartWithJSJSONApi() {
81-
* this.$.mychart.updateConfiguration({
82-
* title: {
83-
* text: 'The chart title'
84-
* },
85-
* subtitle: {
86-
* text: 'Subtitle'
87-
* },
88-
* xAxis: {
89-
* categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
90-
* },
91-
* series: [{
92-
* type: 'column',
93-
* data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]
94-
* }]
95-
* });
96-
* }
97-
* ```
98-
* 1. Call that function from connectedCallback (when the element is added to a document)
9965
* ```js
100-
* connectedCallback() {
101-
* super.connectedCallback();
102-
* this.initChartWithJSJSONApi();
103-
* }
66+
* const chart = document.querySelector('vaadin-chart');
67+
* chart.updateConfiguration({
68+
* title: {
69+
* text: 'The chart title'
70+
* },
71+
* subtitle: {
72+
* text: 'Subtitle'
73+
* },
74+
* xAxis: {
75+
* categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
76+
* },
77+
* series: [{
78+
* type: 'column',
79+
* data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]
80+
* }]
81+
* });
10482
* ```
10583
*
106-
* It should be noted that chart style customization cannot be done via the JS or JSON API.
84+
* **Note:** chart style customization cannot be done via the JS or JSON API.
10785
* Styling properties in the JSON configuration will be ignored. The following section discusses chart styling.
10886
*
10987
* ### CSS Styling

‎packages/charts/src/vaadin-chart.js‎

Lines changed: 43 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -26,89 +26,67 @@ import { ChartMixin } from './vaadin-chart-mixin.js';
2626
* There are two ways of configuring your `<vaadin-chart>` element: **HTML API**, **JS API** and **JSON API**.
2727
* Note that you can make use of all APIs in your element.
2828
*
29-
* #### Configuring your chart using HTML API
29+
* #### Using HTML API
3030
*
3131
* `vaadin-chart` has a set of attributes to make it easier for you to customize your chart.
3232
*
3333
* ```html
34-
* <vaadin-chart title="The chart title" subtitle="The chart subtitle">
35-
* <vaadin-chart-series
36-
* type="column"
37-
* title="The series title"
38-
* values="[10,20,30]">
39-
* </vaadin-chart-series>
40-
* </vaadin-chart>
34+
* <vaadin-chart title="The chart title" subtitle="The chart subtitle">
35+
* <vaadin-chart-series
36+
* type="column"
37+
* title="The series title"
38+
* values="[10, 20, 30]"
39+
* ></vaadin-chart-series>
40+
* </vaadin-chart>
4141
* ```
4242
*
4343
* > Note that while you can set type for each series individually, for some types, such as `'bar'`, `'gauge'` and `'solidgauge'`, you
4444
* > have to set it as the default series type on `<vaadin-chart>` in order to work properly.
4545
*
46-
* #### Configuring your chart using JS API
46+
* #### Using JS API
47+
*
48+
* Use [`configuration`](#/elements/vaadin-chart#property-configuration) property to set chart title, categories and data:
4749
*
48-
* 1. Set an id for the `<vaadin-chart>` in the template
49-
* ```html
50-
* <vaadin-chart id="mychart"></vaadin-chart>
51-
* ```
52-
* 1. Add a function that uses `configuration` property (JS Api) to set chart title, categories and data
53-
* ```js
54-
* initChartWithJSApi() {
55-
* requestAnimationFrame(() => {
56-
* const configuration = this.$.mychart.configuration;
57-
* configuration.setTitle({ text: 'The chart title' });
58-
* // By default there is one X axis, it is referenced by configuration.xAxis[0].
59-
* configuration.xAxis[0].setCategories(['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']);
60-
* configuration.addSeries({
61-
* type: 'column',
62-
* data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]
63-
* });
64-
* });
65-
* }
66-
* ```
67-
* 1. Call that function from connectedCallback (when the element is added to a document)
6850
* ```js
69-
* connectedCallback() {
70-
* super.connectedCallback();
71-
* this.initChartWithJSApi();
72-
* }
51+
* const chart = document.querySelector('vaadin-chart');
52+
*
53+
* // Wait for default configuration to be ready
54+
* requestAnimationFrame(() => {
55+
* const configuration = chart.configuration;
56+
* configuration.setTitle({ text: 'The chart title' });
57+
* // By default there is one X axis, it is referenced by configuration.xAxis[0].
58+
* configuration.xAxis[0].setCategories(['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']);
59+
* configuration.addSeries({
60+
* type: 'column',
61+
* data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]
62+
* });
63+
* });
7364
* ```
7465
*
75-
* #### Configuring your chart using JS JSON API
66+
* #### Using JS JSON API
7667
*
77-
* JS JSON API is a simple alternative to the JS API.
68+
* Use [`updateConfiguration`](#/elements/vaadin-chart#method-updateConfiguration) method to set chart title, categories and data:
7869
*
79-
* 1. Set an id for the `<vaadin-chart>` in the template
80-
* ```html
81-
* <vaadin-chart id="mychart"></vaadin-chart>
82-
* ```
83-
* 1. Add a function that uses `updateConfiguration` method (JS JSON Api) to set chart title, categories and data
84-
* ```js
85-
* initChartWithJSJSONApi() {
86-
* this.$.mychart.updateConfiguration({
87-
* title: {
88-
* text: 'The chart title'
89-
* },
90-
* subtitle: {
91-
* text: 'Subtitle'
92-
* },
93-
* xAxis: {
94-
* categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
95-
* },
96-
* series: [{
97-
* type: 'column',
98-
* data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]
99-
* }]
100-
* });
101-
* }
102-
* ```
103-
* 1. Call that function from connectedCallback (when the element is added to a document)
10470
* ```js
105-
* connectedCallback() {
106-
* super.connectedCallback();
107-
* this.initChartWithJSJSONApi();
108-
* }
71+
* const chart = document.querySelector('vaadin-chart');
72+
* chart.updateConfiguration({
73+
* title: {
74+
* text: 'The chart title'
75+
* },
76+
* subtitle: {
77+
* text: 'Subtitle'
78+
* },
79+
* xAxis: {
80+
* categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
81+
* },
82+
* series: [{
83+
* type: 'column',
84+
* data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]
85+
* }]
86+
* });
10987
* ```
11088
*
111-
* It should be noted that chart style customization cannot be done via the JS or JSON API.
89+
* **Note:** chart style customization cannot be done via the JS or JSON API.
11290
* Styling properties in the JSON configuration will be ignored. The following section discusses chart styling.
11391
*
11492
* ### CSS Styling

0 commit comments

Comments
 (0)