Stream: rustdoc

Topic: macros named "str" considered harmful


view this post on Zulip Mario Carneiro (Feb 01 2021 at 14:57):

I had to tear my project apart to find the cause of this bug. It turns out that a private macro in a completely separate module can cause intra doc links to break.

mod bar {
    macro_rules! str {() => {}}
}

pub mod foo {
    use std::path::{Path, PathBuf};

    pub struct Foo(PathBuf);
    impl std::ops::Deref for Foo {
        type Target = Path;
        fn deref(&self) -> &Path { &self.0 }
    }
}

If you run cargo doc on this, the documentation on Foo::to_str() coming from the deref impl, which contains

Yields a &str slice if the Path is valid unicode.

will link directly to str (not the macro str!, just a broken link to the same directory). If you remove the macro it correctly links to the str documentation in the standard library.

view this post on Zulip Daniel Henry-Mantilla (Feb 01 2021 at 15:26):

(deleted)

view this post on Zulip Joshua Nelson (Feb 01 2021 at 16:57):

@Mario Carneiro this is a bug, rustdoc should check for this in https://github.com/rust-lang/rust/blob/70b18bc2cbac4712020019f5bf57c00905373205/src/librustdoc/passes/collect_intra_doc_links.rs#L1095-L1101. Can you open an issue?

view this post on Zulip Joshua Nelson (Feb 01 2021 at 17:05):

actually it's twice a bug because the deref documentation should be resolved in the original scope of Path

view this post on Zulip Mario Carneiro (Feb 01 2021 at 17:06):

#81633

view this post on Zulip Mario Carneiro (Feb 01 2021 at 17:08):

Is it a bad idea to have macros named str? I was half expecting that not to work because of the name shadowing but rust didn't complain so I figured it was fine, bugs notwithstanding

view this post on Zulip Joshua Nelson (Feb 01 2021 at 17:11):

I mean it's probably confusing but I don't think it's wrong

view this post on Zulip Mario Carneiro (Feb 01 2021 at 17:13):

Since it gets written str! most of the time it isn't normally a disambiguation hazard, although intra-doc links might be an exception

view this post on Zulip Joshua Nelson (Feb 01 2021 at 17:14):

intra-doc links should warn about ambiguity though

view this post on Zulip Joshua Nelson (Feb 01 2021 at 17:14):

you found an edge case where they didn't, but they should

view this post on Zulip Noah Lev (Feb 01 2021 at 21:20):

Yes, they should make you explicitly use either prim@str or str! in this case.


Last updated: Oct 11 2021 at 22:34 UTC