RFC: Formally document prop function signatures

[levithomason]

Issue

Currently, props that take a function do not formally document their signatures. We have inconsistent/informal function signature documentation, like in Rating onRate:

Not only is this inconsistent, but there is no validation nor linting to aide contribution. We should start formally documenting these.

Proposal

One approach could be to use standard JSDoc tags, which we are already parsing and using.

/**
 * Called after user selects a new rating.
 * @param {SyntheticEvent} event
 * @param {object} data
 * @param {*} data.rating
 * @param {*} data.maxRating
 * @return {void}
 */
onRate: PropTypes.func,

We could then construct a formal signature in ComponentProps.js with the docs/app/docgenInfo.json in any format. It could be placed in the description column or type column. It might look something like:

void onRate(
  SyntheticEvent event,
  Object data
  Number data.rating
  Number data.maxRating
)

Details:

We use a custom plugin stardust/gulp/plugins/gulp-react-docgen.js to parse doc blocks on propType and components. It handles parsing JSDoc tags with doctrine. All this info is written to a single JSON file, docs/app/docgenInfo.json. There are React components for the docs that read this JSON info in order to generate descriptions, props info, etc.

[dvdzkwsk]

Would be nice if this was done in a way that allowed us to easily generate TS/Flow definitions.

[levithomason]

On that note, I've been considering completely abstracting our props definitions into a plain object. It has several benefits:

1. Generate better docs. react-docgen is great, though we've had to extend it already and it still can't detect most of our props types and enums. We'd have to write custom AST parsers to do this. A plain object would allow us to generate docs for literally anything with ease.

2. Component Explorer / Sandbox, see feat(docs): add component explorer #427. If we had a single plain object with all the information necessary about props, then we could have a completely automated component explorer. Currently, we can't merge that since it relies on reading propTypes, which again, are severely lacking support for all our uses.

3. Generate definitions for anything, propTypes/Flow/TS/etc. With a plain object that describes the props, it would be trivial to parse it and generate definitions for what ever you wanted.

4. FWIW, I recently read on a React issue that Facebook has considered/wants to remove PropTypes from React. Not sure if this means "into a separate package" or simply drop support for it altogether. In either case, having a plain object abstraction frees us from implementation constraints.

5. Currently, propTypes live in the production source. This could easily live in a separate file to keep the component small. Then, if we generated propTypes, it might be something like:

   import propDefinition from './propDefinition.js`
   
   class Foo extends Component {
     propTypes = makePropTypes(propDefinition)
   }

[levithomason]

This will be done as a result of #623 which also includes tasks lists. We will also be able to parse this as a plain object and do with it what we may. Closing in favor of the other issue.

[levithomason]

Many components now document their callback signatures. I've shipped an update to the docs to display this: