Many `From` implementations are undocumented

[skade]

While std::convert::From has very detailed high level documentation, the implementations often lack docs on how they work and use the default "performs the conversion" boilerplate.

This at least includes all String methods, also, all integer conversions. Both of these can have interesting behaviour, especially in relation to each other. For example, the different allocation behaviour between From<Box<str>> and From<&'a str> is notable and hard to figure out from the source, as it goes through three layers of indirection.

[skade]

@frewsxcv After speaking to @steveklabnik, I'd be willing to mentor this. Can you add the E-easy and E-mentor labels and assign me?

[skade]

Tutorial

To fix this issue, we have to go through the whole rustc codebase
and document all impl From implementations.

std::convert::From represents the
possible conversion from one type to another. This conversion is usually cheap,
but the exact nature of it is not specified. Currently, most implementations
in the std lib are using the standard documentation "performs the conversion".

The goal is to improve this situation.

Picking a task

This assumes some basic git knowledge. If you need help with git, this short tutorial
covers all you need.

1. Pick a file from the rustc source that has undocumented From implementations.
2. Write a comment here, mentioning @skade that you want to work on this file.

• This is to ensure that you don't do double work

3. Download rust-lang/rust and create a branch
4. Document the from function like this:

impl From<Foo> for Bar {
    /// Converts a `Foo` into a `Bar`.
    /// This conversion does not allocate.
    fn from(f: Foo) -> Bar {
        //....
    }
}

5. Post a pull request and add a link to it to this issue.

What to document

Have a close look at the implementation and try to find out what it does.
Write that down. The implementation might be spread and refer to other functions,
follow as deep as you need. Write down everything you learn in the documentation.

Keep an eye out for:

• Heap allocations ("The result is allocated on the heap" [or not])
• Give a rough estimate of the cost. ("The conversion copies the data" or "The conversion happens in place")
• Is the conversion free? (yes, this may happen and should be documented)

Don't feel bad if the resulting text feels formulaic or repetetive, that's very
usual in documentation.

If you have some brain cycles free, try to find a clear, understandable wording.
But don't overthink it, we will improve during review together.

If you are confused or stuck, please get back here as well. This is what
the mentor can help with.

[skade]

This is an incomplete list of From implementations, found with rg "impl From<". Others, especially in macros, may be found.

• libproc_macro/lib.rs
  156:impl From for TokenStream {
  550:impl From for TokenTree {
  557:impl From for TokenTree {
  564:impl From for TokenTree {
  571:impl From for TokenTree {

• libsyntax/tokenstream.rs
  194:impl From for TokenStream {
  200:impl From for TokenStream {
  565:impl From for ThinTokenStream {
  576:impl From for TokenStream {

• libserialize/json.rs
  367:impl Fromfmt::Error for EncoderError {

• liballoc/boxed.rs
  442:impl From<Box> for Box<[u8]> {

• liballoc/string.rs
  2209:impl From<Box> for String {
  2218:impl From for Box {
  2277:impl From for Vec {

• liballoc/arc.rs
  1422:impl From for Arc {

• liballoc/rc.rs
  1101:impl From for Rc {

• libstd/error.rs
  167:impl From for Box<Error + Send + Sync> {
  187:impl From for Box {

• libsyntax_pos/lib.rs
  115:impl From for FileName {
  643:impl From for MultiSpan {
  649:impl From<Vec> for MultiSpan {

• libstd/path.rs
  1402:impl From<Box> for PathBuf {
  1409:impl From for Box {
  1423:impl From for PathBuf {
  1430:impl From for OsString {
  1437:impl From for PathBuf {
  1524:impl From for Arc {
  1542:impl From for Rc {

• libstd/process.rs
  975:impl From for Stdio {
  982:impl From for Stdio {
  989:impl From for Stdio {
  996:impl Fromfs::File for Stdio {

• libcore/alloc.rs
  394:impl From for CollectionAllocErr {
  402:impl From for CollectionAllocErr {

• libcore/task.rs
  173:impl From for Waker {

• libsyntax/parse/parser.rs
  498:impl From<Option<ThinVec>> for LhsExpr {
  508:impl From<P> for LhsExpr {

• libstd/sys_common/process.rs
  28:impl From for DefaultEnvKey {
  32:impl From for OsString {

• libstd/ffi/os_str.rs
  350:impl From for OsString {
  618:impl From<Box> for OsString {
  625:impl From for Box {
  632:impl From for Arc {
  650:impl From for Rc {

• libstd/ffi/c_str.rs
  644:impl From for Vec {
  702:impl From<Box> for CString {
  710:impl From for Box {
  742:impl From for Arc {
  760:impl From for Rc {
  833:impl From for io::Error {

• libstd/io/error.rs
  223:impl From for Error {

• libstd/net/addr.rs
  556:impl From for SocketAddr {
  563:impl From for SocketAddr {

• libstd/net/ip.rs
  665:impl From for IpAddr {
  672:impl From for IpAddr {
  780:impl From for u32 {
  798:impl From for Ipv4Addr {
  815:impl From<[u8; 4]> for Ipv4Addr {
  830:impl From<[u8; 4]> for IpAddr {
  1395:impl From for u128 {
  1404:impl From for Ipv6Addr {
  1415:impl From<[u8; 16]> for Ipv6Addr {
  1424:impl From<[u16; 8]> for Ipv6Addr {
  1433:impl From<[u8; 16]> for IpAddr {
  1461:impl From<[u16; 8]> for IpAddr {

• libcore/char/convert.rs
  117:impl From for u32 {
  143:impl From for char {

• libcore/sync/atomic.rs
  933:impl From for AtomicBool {
  985: impl From<$int_type> for $atomic_type {

• libcore/tests/pattern.rs
  36:impl From for Step {
  46:impl From<Option<(usize, usize)>> for Step {

• libcore/num/mod.rs
  4410:impl From<!> for TryFromIntError {
  4714: impl From<$Small> for $Large {

• libstd/sys/redox/time.rs
  188:impl Fromsyscall::TimeSpec for SystemTime {

• libstd/sys/unix/time.rs
  209: impl Fromlibc::timeval for SystemTime {
  218: impl Fromlibc::timespec for SystemTime {
  333: impl Fromlibc::timespec for SystemTime {

• libstd/sys/redox/process.rs
  401:impl From for Stdio {
  407:impl From for Stdio {
  467:impl From for ExitStatus {

• libstd/sys/wasm/process.rs
  73:impl From for Stdio {
  79:impl From for Stdio {

• libstd/sys/windows/time.rs
  171:impl From<c::FILETIME> for SystemTime {

• libstd/sys/windows/process.rs
  44:impl From for WindowsEnvKey {
  52:impl From for OsString {
  315:impl From for Stdio {
  321:impl From for Stdio {
  398:impl From<c::DWORD> for ExitStatus {

• libstd/sync/mpsc/mod.rs
  1751:impl From for TryRecvError {
  1792:impl From for RecvTimeoutError {

• libstd/sys/cloudabi/shims/process.rs
  71:impl From for Stdio {
  77:impl From for Stdio {

• libstd/sys/unix/process/process_common.rs
  317:impl From for Stdio {
  323:impl From for Stdio {
  383:impl From<c_int> for ExitStatus {

• libstd/sys/redox/net/dns/mod.rs
  45:impl From for n16 {
  54:impl From for u16 {

[gruberb]

Hey @skade, I would be up for the task. I skimmed through libstd/path.rs and would like to take it.

I have experienced with JavaScript (and some other languages), but just played around with Rust a bit. Therefore would need some help.

[cruessler]

I’d like to help. Can I work on libstd/net/ip.rs?

[skade]

@cruessler Sure!