API docs not generated for imported types

[rosskevin]

Problem description

Example: Hidden API docs import type {HiddenProps} from './types'. This is done to prevent a cyclic dependency problem, as the HiddenProps are imported by three (to be four) files:

1. Hidden
2. HiddenJs
3. HiddenCss (TBD)
4. Grid (tight integration with Hidden)

I am very strongly against duplicating props just so we have documentation. In this case, we have two public components so we would probably have three copies of a reasonably extensive set of properties.

This is not the lone case, as our responsive components reference type Breakpoint as well, though this one seems easier as it is a bit simpler.

I raised an issue and learned that react-docgen doesn't resolve imported types. I have been thinking about the solution. Duplication is a last resort and I don't think we are there yet.

Note that this is not specific to use of flow, it is also a problem importing reusable prop-types.

I am open to ideas on solutions. It is something that must be addressed before next is generally available.

[oliviertassinari]

This is not the lone case

Yes, indeed, we have the very same issue between Switch, Radio and Checkbox.

I am very strongly against duplicating props just so we have documentation

I think that it's even worse to have a duplication between the documentation and the source code.
That's why I propose to duplicate the properties in the source code, at least it's in the same domain, we don't have to worry of resetting /docs/src/pages/component-api.

[rosskevin]

I disagree, we have time to get the docs generation right, let's not cloud the source. I am staunchly against duplication of any kind.

[rosskevin]

I started some experiments:
https://github.com/alienfast/material-ui/tree/docs-flow-type-import/scripts/api-docs

I'm not very familiar with the toolset but it seems quite reasonable from my initial time with it. I've asked for some guidance from the react-docgen project.

[oliviertassinari]

@rosskevin Should we close this issue? I can live with the duplication.

[rosskevin]

Yes

[oliviertassinari]

@rosskevin Thanks :)