Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Prescribe something about type parameter documentation #111

Open
djc opened this Issue Jul 20, 2017 · 0 comments

Comments

Projects
None yet
2 participants
@djc
Copy link

djc commented Jul 20, 2017

Here's an example I came across today, from an underdocumented part of nom:

http://rust.unhandledexpression.com/nom/struct.MapConsumer.html

Which, to wit, has <'a, C: 'a, R, S, T, E, M, F> as type parameters, and fails to explain even a single one of them.

For another example, tokio-proto has this for ClientProxy:

https://tokio-rs.github.io/tokio-proto/tokio_proto/util/client_proxy/struct.ClientProxy.html

The use of R, S, and E are not that obvious until you look at the associated types, but looking at the top-level documentation it's pretty unclear what these types signify. It would be great if these guidelines could mandate (a) more readable type parameter names, or, failing that, (b) clear documentation on the meaning of the type parameters for particular types.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.