[docs] Inherited props are not documented

[leesei]

Many components uses EnhancedButton and hence support onTouchTap() attribute (by passing through {...others})
onTouchTap() is crucial to handling click/tap for buttons, however this was not documented in:

• Flat Button
• Raised Button
• Floating Action Button
• Icon Button

Same with:

• DatePicker

Is this intentional?

[leesei]

Alas, I've just found out that onTouchTap() was provided by zilverline/react-tap-event-plugin.
But now with the move to include it internally (#3068/#3079), we should update the doc to state that onTouchTap() is available on all components.

[newoga]

@leesei Yeah honestly I can't think of a good reason why it isn't already documented. It's even documented in other components. Even though we're investigating including it in #3068 and #3079, the react-tap-event-plugin is a prerequisite for material-ui. Feel free to open up a PR to add the prop for us! 😄

Thanks!

[alitaheri]

It's because it's one of the props that are forwarded. We really have to document those props that are passed down with {...other}! something like: inherited props.

[newoga]

Oh, you mean to passed to <EnhancedButton />. I see. Yeah I wonder what the best approach to documenting that is. That would be useful information in general.

[leesei]

I would like to know if it is desirable to hide EnhancedButton from the user?
If so we have to copy and paste those interited props to every button.

Otherwise it is better to add EnhancedButton to the doc and specify its props, and refer to it in the users' doc.

[alitaheri]

@leesei That also works, except that some of the props are intercepted. so not all props are passed down, and not all props are inherited from EnhancedButton. This needs a lots of thought. I have no idea how we can achieve this 😅 😅

[leesei]

Then it's better to manually trace the props for each class and document what props will eventually be handled.
That's indeed a daunting task.

---

Or we can still add doc for EnhancedButton and also document in the user class what is passed down.

[alitaheri]

@leesei That can also work, but exposing internal components scares me O.o Although it might not be a bad idea to have an internal section for this purpose and tell users not to directly use these components O.o

@oliviertassinari @newoga @mbrookes I would like to hear your insight on this too. thanks ^_^

[leesei]

My philosophy too is to hide implementation details. Library users have a tendency to abuse them if there is an easy way to get that info.

[alitaheri]

True that 😅 😅

[mbrookes]

There's a related issue: #2940

I don't know the right answer - @alitaheri hit the nail on the head: #3172 (comment)

So just exposing EnhancedButton in the docs doesn't solve the problem.

[oliviertassinari]

If so we have to copy and paste those interited props to every button.

I feel like this is our best option. We should only document our public API, we can't predict how properties will be passed down to internal components.

There's a related issue: #2940

That's a really interesting problem. The Date Picker, is special. We are not only exposing DatePicker but also DatePickerDialog. People can built their own DatePicker with this second component. Same here, I think that we should add the default value of properties to the DatePicker component.