Annotate callback parameters

[oyvindberg]

So, I know the React world hasn't really embraced this yet - somehow all functions are equal for the prop types. I wanted to bring this up since you are doing a pass over/inlining the documentation anyway. Would you consider enforcing/documenting callback parameters while you're at it?

ideally we could write custom prop types for functions:

    /**
     * Callback function for when the title text is selected via a touch tap.
     */
    onTitleTouchTap: Mui.PropTypes.func1(Mui.PropTypes.Event.isRequired),

Or alternatively, there would be some value in a textual description too :

    /**
     * Callback function for when the title text is selected via a touch tap.
     * @arg Mouse or Touch event
     */
    onTitleTouchTap: React.PropTypes.func,

Or whatever else have you that already exists in some form. I would definitely be willing to help out here if you agree it's a good idea.

[oliviertassinari]

I like the first example.
It would allow us to check the function parameters at run time and improve the document geneneration.
However, reactjs/react-docgen#33 would probably need to be resolved first.

For the second example, I'm not sure this is supported by react-docgen: to try.

[oyvindberg]

Yeah, i noticed that functionality was missing myself the other day while looking at it. For material-ui we need it already to support the custom prop types in prop-types.js.

I have no idea how much work it would be to hack react-docgen into supporting it. sounds easy, but... hehe. im not a terribly good js developer, for one :)

[alitaheri]

@oliviertassinari We shouldn't check the provided callback to see if it's correct. Because people might want to pass a function that takes nothing for the purpose of only knowing about the event, or takes a lot of other things.

I like the second example more though. we can really extend it good with doctrine. Checkout how awesome it is :D

Oliver it's easy to just pass the description text to that lib to get a json structure so we can generate our own way of representing the callbacks. what do you say?

we can use @param tags to represent the values that will be passed to the callback

[oliviertassinari]

@alitaheri Wow, doctrine looks awesome.
You definitly changed my mind 👍.

[alitaheri]

@oliviertassinari Thanks 😁 I'll try to tackle with it a bit to see how we should use the output and generate proper signature documentation. We definitely need this 👍 👍

[oliviertassinari]

We have chosen to implement solution n°2.
Now, we should document all of our function parameters.

[alitaheri]

Now, we should document all of our function parameters.

Oooh right... there's that...

[oliviertassinari]

Well, that's not a priority for me 😁.

[alitaheri]

I've got it, don't worry 😁

[oliviertassinari]

Please refer to #3096 now.