Prescribe something about type parameter documentation #111
djc
started this conversation in
API Guidelines
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
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
, andE
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.Beta Was this translation helpful? Give feedback.
All reactions