Proposal: Use underscore for internal props

[alitaheri]

Since we are making the components composable, we will need some way of passing around props that are implementation details. besides the HOCs for themes will also pass down props, these props shouldn't be directly set, put rather via another internal component. Also we can filter names that start with underscore from the documentation. I think this will express the purpose of these props very well. something like _muiTheme instead of muiTheme that can be excluded from the documentation. or many other component that have someway of communicating with their tightly coupled sister components like Toolbars.

To wrap up starting the internal prop names with underscore has the following advantages:

1. Exclusion from documentations
2. Avoid confusion as why some props exist (underscore will tell them it will be passed down from other components.
3. No doc = No commitment! They can be easily changed without breaking user code in any iteration since they will be classified as implementation detail, not parts of the public API.

@oliviertassinari @newoga @chrismcv @mbrookes Please give me your opinion on this.

[oliviertassinari]

To raise the discussion, another way to do it, would be to blacklist muiTheme from the documentation generation.

[alitaheri]

@oliviertassinari muiTheme might not be the only prop. But it's not a bad idea either :D With internal props we can have much more control over how components communicate with each other. And we can just edit thing as we like since they are private. no more deprecation warning, no more deferred removal and no more breaking change for these private props. We can have them as we like. it's just that underscore is the convention to express it.

[newoga]

I'm agree that we could use some kind of approach for managing/differentiating/hiding internal props from others. I think hiding them from the docs is a good start, and I'm open to naming conventions as well. Like @subjectix said, if it's a truly and internal use only prop, we could technically change the name or naming convention of those props without it impacting users (or having to provide deprecation warnings).

Another thought is that we might be able to use something like ES6 symbols to provide a warning or error if someone attempts to supply a value for an internal prop.

I know in an other issue/pull request we mentioned there were something we'd like to do to improve the docs/codegen. Could it make sense to create an umbrella issue to cover those improvements and include hiding internal props as one of those?

[alitaheri]

@newoga Yeah definitely, an umbrella issue to address these would be great. 👍 Any chance you got the time to compose that? I've got my hands full with the themeManager 😁

[newoga]

@subjectix No problem, I created it the issue here: #2586

[alitaheri]

@newoga thanks a lot 👍

[alitaheri]

Not now with @ignore 😁

[oliviertassinari]

@alitaheri Thanks for solving this. @ignore is an excellent idea and already implemented 👍.

[alitaheri]

Thanks 😁