Hidden trait implementation in online docs

mkbanchi · June 18, 2021, 12:03pm

Looking at nightly documentation for core::ptr::NonNull, i don't see implementation for From<Unique<T>>, but it is there looking at sources. Is this due to the fact that implementation is marked as unstable? I'm missing something?

alice · June 18, 2021, 12:11pm

The Unique type is marked #[doc(hidden)], and is not visible anywhere in the documentation.

mkbanchi · June 18, 2021, 12:55pm

Thanks for your reply,

I cannot find Unique<T> having #[doc(hidden)]. Hovewer i was incorrecty looking at core::ptr::NonNull and not at std::ptr::NonNull. Stable and nightly documentations list correctly that implementation for std::ptr::NonNull:

https://doc.rust-lang.org/std/ptr/struct.NonNull.html
https://doc.rust-lang.org/nightly/std/ptr/struct.NonNull.html

Yandros · June 18, 2021, 1:54pm

github.com

rust-lang/rust/blob/0aaf56f5fc0f2d64f3202021d0b8d735007d7bcf/library/core/src/ptr/unique.rs#L33

    
      
          /// However the pointer may still dangle if it isn't dereferenced.
          ///
          /// Unlike `*mut T`, `Unique<T>` is covariant over `T`. This should always be correct
          /// for any type which upholds Unique's aliasing requirements.
          #[unstable(
              feature = "ptr_internals",
              issue = "none",
              reason = "use `NonNull` instead and consider `PhantomData<T>` \
                        (if you also use `#[may_dangle]`), `Send`, and/or `Sync`"
          )]
          #[doc(hidden)]
          #[repr(transparent)]
          #[rustc_layout_scalar_valid_range_start(1)]
          pub struct Unique<T: ?Sized> {
              pointer: *const T,
              // NOTE: this marker has no consequences for variance, but is necessary
              // for dropck to understand that we logically own a `T`.
              //
              // For details, see:
              // https://github.com/rust-lang/rfcs/blob/master/text/0769-sound-generic-drop.md#phantom-data
              _marker: PhantomData<T>,

Heh, that's a rustdoc bug: I guess it fails to realize that Unique is hidden when it happens cross-crate (cc @jyn514 @GuillaumeGomez , does that seem plausible?)

GuillaumeGomez · June 18, 2021, 2:13pm

That seems plausible indeed. Please open an issue with a link to the problem (and if possible, a small code reproducing the issue, that'd be awesome!). Thanks in advance!

mkbanchi · June 18, 2021, 2:58pm

Ok, now all is clear. Thanks

steffahn · June 18, 2021, 6:43pm

Recently when reviewing/studying some std code, I found it super useful to use build the documentation locally with --document-private-items --document-hidden-items.

The steps involved are, roughtly, (more general info here)

clone the rust repo git clone https://github.com/rust-lang/rust.git; cd rust
./x.py setup, choose standard library.

then

RUSTDOCFLAGS='--document-private-items --document-hidden-items' ./x.py doc library/std --open

Maybe someone should host a version of those docs online somewhere.

quinedot · June 18, 2021, 8:45pm

I've ran into this and wondered myself -- basically if you build without those flags, the generate "src" documents do not actually contain all of the source code, correct? E.g. this 404, or this one. IMO it should always be built, even if not linked.

In the course of finding those links, I did discover that on docs.rs you can click on the crate name in the upper left, click on "Docs.rs crate page", click on the "Source" tab, and browse the source code there. So, you don't have to go to the repo to be sure. Still, bit of a click fest, discovery problem, and surprise that one contains only a subset of the files.

steffahn · June 18, 2021, 9:05pm

No they seem complete, AFAICT. You need to append .html, e.g.

https://doc.rust-lang.org/nightly/src/core/ptr/unique.rs.html

I was talking about actually documenting everything by using those flags. Which can help a lot, especially around private traits and such; you won’t need to search all the impls by hand. And stuff is linked, etc.

quinedot · June 18, 2021, 9:41pm

Ha! Thanks. Doesn't seem to be true for docs.rs though. (So perhaps I'm just incompetent on this issue today and not every time I've tried to do it.)

I agree documenting everything is better than just having the source available.

Yandros · June 18, 2021, 11:18pm

github.com/rust-lang/rust

cross-crate `#[doc(hidden)]` is ignored when listing trait implementations

opened 09:19PM - 18 Jun 21 UTC

danielhenrymantilla

C-bug T-rustdoc

### Context https://users.rust-lang.org/t/hidden-trait-implementation-in-onli…ne-docs/61256/4 ### Repro ```bash set -euo pipefail cd $(mktemp -d) cargo new -q --lib dependency cat> dependency/src/lib.rs <<'EOF' #[doc(hidden)] pub enum HiddenType {} pub enum MyLibType {} impl From<HiddenType> for MyLibType { fn from (it: HiddenType) -> MyLibType { match it {} } } EOF (cd dependency set -x cargo doc -q --no-deps # No matches ! grep -o HiddenType target/doc/dependency/index.html ) cargo init -q --lib --name mylib cat> src/lib.rs <<'EOF' pub use ::dependency::HiddenType; // OK, not re-exported pub enum MyLibType {} impl From<HiddenType> for MyLibType { fn from (it: HiddenType) -> MyLibType { match it {} } } EOF cat>> Cargo.toml <<'EOF' dependency.path = 'dependency' EOF set -x cargo doc -q --no-deps # No matches ! grep -o HiddenType target/doc/mylib/index.html # There are matches grep -o HiddenType target/doc/mylib/enum.MyLibType.html ``` - Last line yields several occurrences of `HiddenType` in the generated `.html` file. ## Expected behavior No occurrences of `HiddenType` anywhere since it was `#[doc(hidden)]` - [Playground](https://play.rust-lang.org/?version=nightly&mode=debug&edition=2018&gist=14b5e1c16ef0dc2df505fba4d4e2065c) @rustbot label C-bug T-rustdoc cc @GuillaumeGomez

jyn514 · June 26, 2021, 12:29am

Maybe someone should host a version of those docs online somewhere.

https://stdrs.dev/

./x.py setup , choose standard library.

This is more simply written as x.py setup library.

No they seem complete, AFAICT. You need to append .html, e.g.

Rustdoc will only generate a source file if at least one public item is defined there. If only private items are defined in the file, it will not have sources available.

system · September 24, 2021, 12:30am

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.