Rustdoc bring module into scope?

Question

I am writing a documentation for crate and I noticed I am having lot's references like this:

/// A struct [`MyStruct`][`modA::subB::subC::MyStruct`] is very beautiful.

Is there a way to bring module subC into scope within the doc comment? It would be wonderful if I could write something like:

/// #[use modA::subB::subC::MyStruct];
/// A struct [`MyStruct`] is very beautiful.

Is there something like that?

score 1 · Answer 1 · answered Mar 19 '23 at 15:05

1

I don't know if that's the best solution, but you can use a #[cfg(doc)] module that reexports the name:

pub mod super_long_a {
    pub mod super_long_b {
        pub mod super_long_c {
            pub struct Foo;
        }
    }
}

pub mod bar {
    #[cfg(doc)]
    mod doc_links {
        pub(super) use crate::super_long_a::super_long_b::super_long_c::Foo;
    }

    /// See [`Foo`](doc_links::Foo).
    pub fn qux() {}
}

answered Mar 19 '23 at 15:05

Chayim Friedman

47,971
5
48
77

What does it do exactly? – Samuel Hapak Mar 19 '23 at 15:47
@SamuelHapak It creates a reexport and links to it, what is the question? – Chayim Friedman Mar 19 '23 at 15:49
What is the point of ‘#[cfg(doc)]’? – Samuel Hapak Mar 19 '23 at 20:40
2

@SamuelHapak It enables the module only for documentation, not for actual code. – Chayim Friedman Mar 20 '23 at 05:06

Rustdoc bring module into scope?

1 Answers1