Rust’s docs really need something like the ‘key takeaways’ box from this post or some sort of summary of what the different traits that are available that you’re supposed to use in your own libraries.
I didn’t know about ‘TryInto’ and even looked for something like it for about 20 minutes. I ended up creating my own ‘AttemptInto’ in a library I started awhile ago because I didn’t know better.
but their exact details and implications are still under debate, which means they’re still marked as unstable.
I think I just got a little over-excited at first because that was one of the bigger things I had been struggling with how to do it ‘right’. (Before I decided to just make it work first before going back to make it right.)
I’m not sure where exactly it would go and to be honest I haven’t ventured far beyond the book & std library reference, so it’s possible the group of info I’m looking for exists somewhere and I just haven’t found it yet. Is there a way to get a list of all the standard traits with a short description of each somewhere in the docs?
There isn’t, because there’s a lot of them. Such a thing would be really big, and cross-cutting, so it’s unclear of where something like this would go. “Advice for library writers” could be a whole book of its own!
The top of a particular module may be the place for this sort of summary. So, for example, the std::convert docs page could start with a summary akin to the one seen here, followed by a more in-depth explanation, followed by the actual module contents. The question then is how best to write such a summary box in the doc comments, and what (if any) additions are necessary to Rustdoc to make this look as nice and clear as possible.
Yes, in general, that’s my approach to module docs. I haven’t gotten to convert yet, so it’s a bit anemic.
I was reading OP as talking more generally, about all of them. There’s a LOT, and so it would be much less clear to me where it should go; if it were at the top level, it would dominate the rest of the std docs…
Hmm… a list of traits similar to the list of macros on the standard library API docs home page may be good. It would include in it a list of the traits provided by the standard library, with a short description and link to the full documentation for each.
So, a quick skim of the current stable docs finds 78 stable traits. Grouped together into categories, it’s a pretty manageable list. I’ve been tinkering with a crate creation and maintenance guide in my spare time. I may include the type of list and explanation suggested by azdle in there, with a bit about each of these traits.
Nice list. A quick glance makes me wonder if the list would have value to other languages that do type or proof constraints. Might make a nice reference for what could be useful to include or how one might start at expressing it.
This is too much syntax candy for my taste. In my opinion, an idiom should be easy to remember, not a list of dozens of “idioms” you have to look in the docs for to find out about.
This is no syntax candy at all, all of them use the same standard Rust generics syntax. They all work the same, and none of this is an idiom. They are pre-defined conversion types and describe this at a type system level.
Rust’s docs really need something like the ‘key takeaways’ box from this post or some sort of summary of what the different traits that are available that you’re supposed to use in your own libraries.
I didn’t know about ‘TryInto’ and even looked for something like it for about 20 minutes. I ended up creating my own ‘AttemptInto’ in a library I started awhile ago because I didn’t know better.
Where in the docs would such a thing go?
(And the Try* traits are a very recent addition, so that also may be why you missed them)
Heh, just got there in the article
I think I just got a little over-excited at first because that was one of the bigger things I had been struggling with how to do it ‘right’. (Before I decided to just make it work first before going back to make it right.)
I’m not sure where exactly it would go and to be honest I haven’t ventured far beyond the book & std library reference, so it’s possible the group of info I’m looking for exists somewhere and I just haven’t found it yet. Is there a way to get a list of all the standard traits with a short description of each somewhere in the docs?
No worries :)
There isn’t, because there’s a lot of them. Such a thing would be really big, and cross-cutting, so it’s unclear of where something like this would go. “Advice for library writers” could be a whole book of its own!
The top of a particular module may be the place for this sort of summary. So, for example, the
std::convertdocs page could start with a summary akin to the one seen here, followed by a more in-depth explanation, followed by the actual module contents. The question then is how best to write such a summary box in the doc comments, and what (if any) additions are necessary to Rustdoc to make this look as nice and clear as possible.Yes, in general, that’s my approach to module docs. I haven’t gotten to convert yet, so it’s a bit anemic.
I was reading OP as talking more generally, about all of them. There’s a LOT, and so it would be much less clear to me where it should go; if it were at the top level, it would dominate the rest of the std docs…
Hmm… a list of traits similar to the list of macros on the standard library API docs home page may be good. It would include in it a list of the traits provided by the standard library, with a short description and link to the full documentation for each.
This shows off how bad I am at
git grepthan anything else but…It’d be huuuuuuge.
So, a quick skim of the current stable docs finds 78 stable traits. Grouped together into categories, it’s a pretty manageable list. I’ve been tinkering with a crate creation and maintenance guide in my spare time. I may include the type of list and explanation suggested by azdle in there, with a bit about each of these traits.
For reference, here are the traits:
AnyAsciiExtBorrowBorrowMutToOwnedCloneEqOrdPartialEqPartialOrdAsMutAsRefFromIntoDefaultErrorBinaryDebugDisplayLowerExpLowerHexOctalPointerUpperExpUpperHexfmt::WriteBuildHasherHashHasherBufReadReadSeekio::WriteDoubleEndedIteratorExactSizeIteratorExtendFromIteratorIntoIteratorIteratorCopySendSizedSyncToSocketAddrsAddAddAssignBitAndBitAndAssignBitOrBitOrAssignBitXorBitXorAssignDerefDerefMutDivDivAssignDropFnFnMutFnOnceIndexIndexMutMulMulAssignNegNotRemRemAssignShlShlAssignShrShrAssignSubSubAssignRefUnwindSafeUnwindSafeFromStrToStringNice list. A quick glance makes me wonder if the list would have value to other languages that do type or proof constraints. Might make a nice reference for what could be useful to include or how one might start at expressing it.
This is too much syntax candy for my taste. In my opinion, an idiom should be easy to remember, not a list of dozens of “idioms” you have to look in the docs for to find out about.
This is no syntax candy at all, all of them use the same standard Rust generics syntax. They all work the same, and none of this is an idiom. They are pre-defined conversion types and describe this at a type system level.