[Pagination] Leverage @default over default values

[eps1lon]

Using runtime for documentation can be quite confusing. Let's solve docs concerns with jsdoc instead. Both approaches can just as easily become outdated. But the new one doesn't add noise to the implementation.

yarn docs:api will throw if you use a default value and @default in the propTypes even if they have the same value e.g.

function Component(props) {
  const { page = 1 } = props; 
} 
Component.propTypes = { 
  /**
   * @default 1
   */
  page: PropTypes.number 
};

will throw:

Error parsing src for /home/eps1lon/Development/projects/mui/fork/packages/material-ui-lab/src/Pagination/Pagination.js
error building docs for /home/eps1lon/Development/projects/mui/fork/packages/material-ui-lab/src/Pagination/Pagination.js
Error: Can't have JavaScript default value and jsdoc @defaultValue in prop 'boundaryCount'. Remove the @defaultValue if you need the JavaScript default value at runtime.

[mui-pr-bot]

No bundle size changes comparing 41fe2e2...e242671

Generated by 🚫 dangerJS against e242671

[oliviertassinari]

Interesting! It could potentially be used for a couple of other components, the Autocomplete for instance :).

The only point that I wonder about is how does this "direction" affects moving the descriptions of the prop-types in TypeSript?

[eps1lon]

The only point that I wonder about is how does this "direction" affects moving the descriptions of the prop-types in TypeSript?

We probably want to do this at some point anyway. Then we need to be more careful with throwing an error if we find both (probably just verify they're equal). In any case: the default value in the typescript types would be a nice to have.

[eps1lon]

Will be reverted in #22447. The problem is that it's not accurate. The default value in the component for boundaryCount is not 1. Only in usePagination.

[mbrookes]

The only point that I wonder about is how does this "direction" affects moving the descriptions of the prop-types in TypeSript?

OT, but speaking of direction, am I the only one that feels that the current direction for sharing prop descriptions is "backwards"? I routinely edit the component prop descriptions first, so then have to sync them manually, since the script assumes that the type definitions is the singe source of truth. Class names go in the opposite direction.

[eps1lon]

I routinely edit the component prop descriptions first, so then have to sync them manually, since the script assumes that the type definitions is the singe source of truth. Class names go in the opposite direction.

Purely technical decision.

TypeScript declarations have very different shapes to accomodate certain patterns. Figuring out where to put the description is incredibly hard. .propTypes on the other hand have a single pattern that we can easily generate with babel.

Same for classes: This would be slightly easier to figure out where the description goes in the JS file but would still need flow analysis. In TypeScript it's currently a single pattern: A type property with name classes.

Since this is all driven by "routine" I don't think it's worth putting time into it. Sure, a single file would be better (though I'd personally never do this since it discourages extensive documentation). But I feel like we have pretty clear messaging what went wrong with documentation and how to fix it.

[mbrookes]

Figuring out where to put the description is incredibly hard.

Makes sense, thanks.