Rustdoc display reference as publicly exported item

help
1

I have a library with a private module that has its own Error and Result types. In the public api, I re-export them as ParseError and ParseResult. Now I am writing documentation inside the private module. When I link to just Error and Result, rustdoc correctly links to the public facing versions. However, the linked text is still displayed as Error and Result. Is there a way to get rustdoc to display the names of the items it actually links to (ParseError & ParseResult) without explicitly writing them out?

2

No, there is no way to automatically change link text, only explicitly writing [`ParseError`](Error).

However, is there definitely a good reason you're renaming the items? I don't know what the rest of your library API looks like, but (in my opinion) good Rust style is for public items to not have prefixes that could be module names — just like std::io::Error is not std::io::IoError, you should have mylib::parse::Error, not mylib::parse::ParseError — if there is a parse module already, at least.

3

I do indeed have a parse module, which contains a parse function. I wanted to avoid requiring use x::parse::parse; thus I kept it private and re-exported parse. And since there may be more kinds of errors/results in the future, I added a prefix. If it was somehow possible to keep the parse fn in the module private, and re-export it from the main module, then I could keep the Error and Result in parse and let users rename them on import if required.

4

I wouldn’t necessarily recommend it, but modules can have the same names as functions, so having both public is valid:

mod x {
    pub mod parse {
        pub fn parse() -> Result<()> { Ok(()) }
        
        pub struct Error {}
        pub type Result<T, E = Error> = core::result::Result<T, E>;
    }
    
    pub use parse::parse;
}

fn main() {
    let r1 = x::parse();
    let r2 = x::parse::parse();

    use x::parse;
    let r3: parse::Result<()> = parse();
    let r4 = parse::parse();
}