Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.
Sign upPrescribe something about type parameter documentation #111
Comments
dtolnay
added
the
new guideline
label
Sep 18, 2017
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
djc commentedJul 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, andEare 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.