[charts] Improve properties JSDoc #10931

alexfauquette · 2023-11-07T15:41:57Z

The chart's API pages were somewhat empty. It's just because most of the props don't have JSDocs 🫣

I'm adding some of them. I've splited the PR by commit with JSdocs, and commits with scripts

mui-bot · 2023-11-07T15:46:23Z

Deploy preview: https://deploy-preview-10931--material-ui-x.netlify.app/

Generated by 🚫 dangerJS against 34a41d6

LukasTy

Nice improvement! 👏
WDYT about changing the PR title to [charts] Improve properties JSDoc?
It seems that the PR targets props that are also only dev facing, not only the ones that end up in API docs. 🤔

Complete nitpick: Should this PR maybe target next as the source of truth and then be cherry-picked to master?

LukasTy · 2023-11-08T12:42:33Z

packages/x-charts/src/ChartsSurface.tsx

  height: number;
  viewBox?: ViewBox;
  className?: string;
  title?: string;
  desc?: string;
  sx?: SxProps<Theme>;
  children?: React.ReactNode;
+  /**
+   * If true, the charts will not listen to the mouse move event.


Suggested change

* If true, the charts will not listen to the mouse move event.

* If `true`, the charts will not listen to the mouse move event.

LukasTy · 2023-11-08T12:43:03Z

packages/x-charts/src/ChartsSurface.tsx

  height: number;
  viewBox?: ViewBox;
  className?: string;
  title?: string;
  desc?: string;
  sx?: SxProps<Theme>;
  children?: React.ReactNode;
+  /**
+   * If true, the charts will not listen to the mouse move event.
+   * It might breaks interactive features, but save some computation power.


Suggested change

* It might breaks interactive features, but save some computation power.

* It might break interactive features but will improve performance.

LukasTy · 2023-11-08T12:43:32Z

packages/x-charts/src/LineChart/LineChart.tsx

@@ -55,6 +55,13 @@ export interface LineChartProps
    Omit<ChartsAxisProps, 'slots' | 'slotProps'> {
  series: MakeOptional<LineSeriesType, 'type'>[];
  tooltip?: ChartsTooltipProps;
+  /**
+   * Object `{ x, y }` that defines how the charts highlight the mouse position along x and y axes.
+   * The two proerties accept the next values:


Suggested change

* The two proerties accept the next values:

* The two properties accept the following values:

LukasTy · 2023-11-08T12:43:43Z

packages/x-charts/src/LineChart/LineChart.tsx

@@ -55,6 +55,13 @@ export interface LineChartProps
    Omit<ChartsAxisProps, 'slots' | 'slotProps'> {
  series: MakeOptional<LineSeriesType, 'type'>[];
  tooltip?: ChartsTooltipProps;
+  /**
+   * Object `{ x, y }` that defines how the charts highlight the mouse position along x and y axes.


Suggested change

* Object `{ x, y }` that defines how the charts highlight the mouse position along x and y axes.

* Object `{ x, y }` that defines how the charts highlight the mouse position along the x and y axes.

LukasTy · 2023-11-08T12:44:04Z

packages/x-charts/src/LineChart/LineChart.tsx

+   * The two proerties accept the next values:
+   * - 'none': display nothing.
+   * - 'line': display a line at the current mouse position.
+   * - 'band': display a band at the current mouse position. Only available  with band scale.


Suggested change

* - 'band': display a band at the current mouse position. Only available with band scale.

* - 'band': display a band at the current mouse position. Only available with band scale.

LukasTy · 2023-11-08T13:05:21Z

packages/x-charts/src/models/layout.ts

@@ -8,5 +8,11 @@ export interface CardinalDirections<T> {
 export type LayoutConfig = {
  width: number;
  height: number;
+  /**
+   * The margin between the SVG and the drawing area.
+   * It's used for leving space for extra information wuch as axes, or legend.


Suggested change

* It's used for leving space for extra information wuch as axes, or legend.

* It's used for leaving space for extra information such as axes, or legend.

LukasTy · 2023-11-08T13:05:42Z

packages/x-charts/src/models/layout.ts

+  /**
+   * The margin between the SVG and the drawing area.
+   * It's used for leving space for extra information wuch as axes, or legend.
+   * Accept and object with some of the next properties: `top`, `bottom`, `left`, and `right`.


Suggested change

* Accept and object with some of the next properties: `top`, `bottom`, `left`, and `right`.

* Accepts an object with some of the following properties: `top`, `bottom`, `left`, and `right`.

LukasTy · 2023-11-08T13:08:12Z

packages/x-charts/src/models/seriesType/common.ts

  yAxisKey?: string;
 };

 export type StackableSeriesType = {
+  /**
+   * The key that identify the stacking group.


Suggested change

* The key that identify the stacking group.

* The key that identifies the stacking group.

LukasTy · 2023-11-08T13:08:51Z

packages/x-charts/src/models/seriesType/common.ts

  stack?: string;
+  /**
+   * Defines hos staked series handle negative values.


Suggested change

* Defines hos staked series handle negative values.

* Defines how stacked series handles negative values.

LukasTy · 2023-11-08T13:10:49Z

packages/x-charts/src/models/seriesType/common.ts

  stackOffset?: StackOffsetType;
+  /**
+   * The order in which series of the  same staking group are staked together.


Suggested change

* The order in which series of the same staking group are staked together.

* The order in which series of the same staking group are staked together.

alexfauquette · 2023-11-08T13:29:39Z

Complete nitpick: Should this PR maybe target next as the source of truth and then be cherry-picked to master?

As long as there is no breaking change, I backport everything.

michelengelen

SRY for all the comments. A ton of them are duplicates, but midway through I couldn't stop anymore! 🙇🏼 🙇🏼 🙇🏼

michelengelen · 2023-11-08T13:02:53Z

packages/x-charts/src/models/seriesType/common.ts

  stackOffset?: StackOffsetType;
+  /**
+   * The order in which series of the  same staking group are staked together.


Suggested change

* The order in which series of the same staking group are staked together.

* The order in which series' of the same group are stacked together.

michelengelen · 2023-11-08T13:03:11Z

packages/x-charts/src/models/seriesType/common.ts

  stack?: string;
+  /**
+   * Defines hos staked series handle negative values.


Suggested change

* Defines hos staked series handle negative values.

* Defines how stacked series handle negative values.

michelengelen · 2023-11-08T13:03:32Z

packages/x-charts/src/models/seriesType/common.ts

  yAxisKey?: string;
 };

 export type StackableSeriesType = {
+  /**
+   * The key that identify the stacking group.


Suggested change

* The key that identify the stacking group.

* The key that identifies the stacking group.

michelengelen · 2023-11-08T13:05:54Z

packages/x-charts/src/models/layout.ts

+  /**
+   * The margin between the SVG and the drawing area.
+   * It's used for leving space for extra information wuch as axes, or legend.
+   * Accept and object with some of the next properties: `top`, `bottom`, `left`, and `right`.
+   * @default object depends on the charts type.
+   */


Suggested change

/**

* The margin between the SVG and the drawing area.

* It's used for leving space for extra information wuch as axes, or legend.

* Accept and object with some of the next properties: `top`, `bottom`, `left`, and `right`.

* @default object depends on the charts type.

*/

/**

* The margin between the SVG and the drawing area.

* It's used for leaving some space for extra information such as the x- and y-axis or legend.

* Accepts an object with the optional properties: `top`, `bottom`, `left`, and `right`.

* @default object Depends on the charts type.

*/

michelengelen · 2023-11-08T13:10:08Z

packages/x-charts/src/models/axis.ts

@@ -202,6 +216,9 @@ export type AxisDefaultized<S extends ScaleName = ScaleName, V = any> = Omit<
  'scaleType'
 > &
  AxisScaleConfig[S] & {
+    /**
+     * An indication of the number of ticks expected.


Not to sure about this indication.

Could be either ...

Suggested change

* An indication of the number of ticks expected.

* An indication of the expected number of ticks.

or ...

Suggested change

* An indication of the number of ticks expected.

* The expected number of ticks.

michelengelen · 2023-11-08T13:34:08Z

packages/x-charts/src/ChartsSurface.tsx

+  /**
+   * If true, the charts will not listen to the mouse move event.
+   * It might breaks interactive features, but save some computation power.
+   * @default false
+   */


Suggested change

/**

* If true, the charts will not listen to the mouse move event.

* It might breaks interactive features, but save some computation power.

* @default false

*/

/**

* If `true`, the charts will not listen to the mouse move event.

* It might break interactive features, but is improving performance.

* @default false

*/

michelengelen · 2023-11-08T13:34:17Z

packages/x-charts/src/BarChart/BarChart.tsx

+  /**
+   * If true, the charts will not listen to the mouse move event.
+   * It might breaks interactive features, but save some computation power.
+   * @default false
+   */


Suggested change

/**

* If true, the charts will not listen to the mouse move event.

* It might breaks interactive features, but save some computation power.

* @default false

*/

/**

* If `true`, the charts will not listen to the mouse move event.

* It might break interactive features, but is improving performance.

* @default false

*/

michelengelen · 2023-11-08T13:35:00Z

packages/x-charts/src/BarChart/BarChart.tsx

+  /**
+   * The margin between the SVG and the drawing area.
+   * It's used for leving space for extra information wuch as axes, or legend.
+   * Accept and object with some of the next properties: `top`, `bottom`, `left`, and `right`.
+   * @default object depends on the charts type.
+   */


Suggested change

/**

* The margin between the SVG and the drawing area.

* It's used for leving space for extra information wuch as axes, or legend.

* Accept and object with some of the next properties: `top`, `bottom`, `left`, and `right`.

* @default object depends on the charts type.

*/

/**

* The margin between the SVG and the drawing area.

* It's used for leaving some space for extra information such as the x- and y-axis or legend.

* Accepts an object with the optional properties: `top`, `bottom`, `left`, and `right`.

* @default object Depends on the charts type.

*/

packages/x-charts/src/BarChart/BarChart.tsx

alexfauquette · 2023-11-08T14:27:29Z

Thanks for all your comments. I think I nearly integrated each of them 👍

alexfauquette added 2 commits November 7, 2023 16:35

add definitions

58b805e

scripts

cb1df79

alexfauquette added docs Improvements or additions to the documentation component: charts This is the name of the generic UI component, not the React module! labels Nov 7, 2023

alexfauquette requested review from LukasTy and michelengelen November 8, 2023 12:35

LukasTy approved these changes Nov 8, 2023

View reviewed changes

alexfauquette changed the title ~~[docs] Improve docs API coverage~~ [charts] Improve properties JSDoc Nov 8, 2023

michelengelen reviewed Nov 8, 2023

View reviewed changes

feedbacks

34a41d6

alexfauquette merged commit a0be8ca into mui:master Nov 8, 2023
5 checks passed

alexfauquette added a commit to alexfauquette/mui-x that referenced this pull request Nov 8, 2023

[charts] Improve properties JSDoc (mui#10931)

004c7d1

alexfauquette added a commit that referenced this pull request Nov 8, 2023

[charts] Improve properties JSDoc (#10931) (#10955)

b13c578

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[charts] Improve properties JSDoc #10931

[charts] Improve properties JSDoc #10931

alexfauquette commented Nov 7, 2023

mui-bot commented Nov 7, 2023 •

edited

Loading

LukasTy left a comment •

edited

Loading

LukasTy Nov 8, 2023

LukasTy Nov 8, 2023

LukasTy Nov 8, 2023

LukasTy Nov 8, 2023

LukasTy Nov 8, 2023

LukasTy Nov 8, 2023

LukasTy Nov 8, 2023

LukasTy Nov 8, 2023

LukasTy Nov 8, 2023

LukasTy Nov 8, 2023

alexfauquette commented Nov 8, 2023

michelengelen left a comment

michelengelen Nov 8, 2023

michelengelen Nov 8, 2023

michelengelen Nov 8, 2023

michelengelen Nov 8, 2023

michelengelen Nov 8, 2023

michelengelen Nov 8, 2023

michelengelen Nov 8, 2023

michelengelen Nov 8, 2023

alexfauquette commented Nov 8, 2023

	* If true, the charts will not listen to the mouse move event.
	* If `true`, the charts will not listen to the mouse move event.

	* It might breaks interactive features, but save some computation power.
	* It might break interactive features but will improve performance.

	* The two proerties accept the next values:
	* The two properties accept the following values:

	* Object `{ x, y }` that defines how the charts highlight the mouse position along x and y axes.
	* Object `{ x, y }` that defines how the charts highlight the mouse position along the x and y axes.

	* - 'band': display a band at the current mouse position. Only available with band scale.
	* - 'band': display a band at the current mouse position. Only available with band scale.

	* It's used for leving space for extra information wuch as axes, or legend.
	* It's used for leaving space for extra information such as axes, or legend.

	* Accept and object with some of the next properties: `top`, `bottom`, `left`, and `right`.
	* Accepts an object with some of the following properties: `top`, `bottom`, `left`, and `right`.

	* The key that identify the stacking group.
	* The key that identifies the stacking group.

	* Defines hos staked series handle negative values.
	* Defines how stacked series handles negative values.

	* The order in which series of the same staking group are staked together.
	* The order in which series of the same staking group are staked together.

	* The order in which series of the same staking group are staked together.
	* The order in which series' of the same group are stacked together.

	* Defines hos staked series handle negative values.
	* Defines how stacked series handle negative values.

	* An indication of the number of ticks expected.
	* An indication of the expected number of ticks.

	* An indication of the number of ticks expected.
	* The expected number of ticks.

[charts] Improve properties JSDoc #10931

[charts] Improve properties JSDoc #10931

Conversation

alexfauquette commented Nov 7, 2023

mui-bot commented Nov 7, 2023 • edited Loading

LukasTy left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexfauquette commented Nov 8, 2023

michelengelen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexfauquette commented Nov 8, 2023

mui-bot commented Nov 7, 2023 •

edited

Loading

LukasTy left a comment •

edited

Loading