Hidden trait implementation in online docs

mkbanchi · 2021-06-18T12:03:19.338Z

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 · 2021-06-18T12:11:15.464Z

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

mkbanchi · 2021-06-18T12:55:23.251Z

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 · 2021-06-18T13:54:38.654Z

mkbanchi:

I cannot find Unique<T> having #[doc(hidden)] .

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>,

mkbanchi:

Stable […] documentations list correctly that implementation for std

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 · 2021-06-18T14:13:50.850Z

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 · 2021-06-18T14:58:08.433Z

Ok, now all is clear. Thanks

steffahn · 2021-06-18T18:43:37.862Z

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 · 2021-06-18T20:45:16.413Z

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 · 2021-06-18T21:05:46.377Z

quinedot:

basically if you build without those flags, the generate "src" documents do not actually contain all of the source code, correct?

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 · 2021-06-18T21:41:16.813Z

steffahn:

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

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 · 2021-06-18T23:18:06.341Z

https://github.com/rust-lang/rust/issues/86448

jyn514 · 2021-06-26T00:29:09.258Z

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 · 2021-09-24T00:30:05.249Z

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.