Alleged type visibility leakage

[fengalin]

Working on a type with a builder, I found it surprising that a documentation link to the builder type was broken.

I set up the following repo as a test case: https://github.com/fengalin/test_builder_visibility.

In my_lib, rustdoc reports:

warning: public documentation for `builder` links to private item `MyTypeBuilder`
 --> my_lib/src/my_type.rs:7:26
  |
7 |     /// Instantiates a [`MyTypeBuilder`].
  |                          ^^^^^^^^^^^^^ this item is private
  |
  = note: this link will resolve properly if you pass `--document-private-items`
  = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default

MyTypeBuilder is declared as a pub struct, however it is not re-exported as pub by my_lib.

rustc disagrees with rustdoc and allows the external main to use a function declared on a MyTypeBuilder instance, obtained by calling MyType::builder().

@GuillaumeGomez requested that I report the issue here.

Meta

Issue observed using:

rustc --version --verbose:

rustc 1.67.0 (fc594f156 2023-01-24)
binary: rustc
commit-hash: fc594f15669680fa70d255faec3ca3fb507c3405
commit-date: 2023-01-24
host: x86_64-unknown-linux-gnu
release: 1.67.0
LLVM version: 15.0.6

&

cargo +nightly --version --verbose:

cargo 1.69.0-nightly (9d5b32f50 2023-02-22)
release: 1.69.0-nightly
commit-hash: 9d5b32f503fc099c4064298465add14d4bce11e6
commit-date: 2023-02-22
host: x86_64-unknown-linux-gnu
libgit2: 1.5.0 (sys:0.16.0 vendored)
libcurl: 7.86.0-DEV (sys:0.4.59+curl-7.86.0 vendored ssl:OpenSSL/1.1.1q)
os: Fedora 37.0.0 [64-bit]

[GuillaumeGomez]

Thanks! I'll take a look in the next days.

[SkiFire13]

Note that rustc does not fully disagree with rustdoc: your MyTypeBuilder is unnameable from outside, only its methods are usable. IMO if MyTypeBuilder was documented by rustdoc then it should also be nameable, it would be pretty weird for the user otherwise.

[fengalin]

We could consider that there's no reason for the user to instantiate MyTypeBuilder directly because the idiomatic way would be to call MyType::builder(). In that case, it would be helpful to generate the documentation, maybe with a mention that the type is unnameable.

(It's not blocking for me fwiw)

[GuillaumeGomez]

If you want a type to be available but make it impossible for users to instantiate it, you can make all constructors private. Like that the type and its methods are public but only the lib can instantiate it. But in any case, I think this is a bug in rustc to not detect this.

[fengalin]

Fair enough :) I guess I was trying to figure out why we could create unnameable types like this.