Could docs.rs have a private switch?

1

cargo doc has a very useful option --document-private-items which is great for checking code, generally looking in detail at how a crate or module works. It seems to me it would be useful if published crates had the same option, without you having to download and run cargo doc on a local copy ( say ). After all, if you are using a crate, and it's a matter of some importance, you ought to be checking the code you are using does what you hope it does, and tools to help with that would I think be good. What do you think of this idea? Perhaps this could be integrated into cargo doc, so whenever documentation is generated, both private and public views are generated rather than one or the other?

4 Likes
2

I’d say, this would make a lot of sense, particularly taking into consideration the fact that viewing the source code is already always an option for Rust documentation.

The same kind of thing would also be quite useful to have for the standard library; it’s a particularly huge pain to have to clone the rust repository just to be able to take a look at private and hidden items in some other way than just by viewing the source code.

Speaking of hidden items, it should probably also include --document-hidden-items (though note that that’s currently still an unstable option only).

Regarding the idea of always having this when generating documentation through rustdoc, that might be a bad idea if it ends up slowing down cargo doc significantly.

3

I have lost count of the number of times I have

  • Looked something up in the Rust std documentation
  • Clicked src
  • Found that it defers to some platform or otherwise private module
  • Sighed heavily
  • Gone to Github and spent a lot of time searching around and trying to follow the unclickable use imports, etc, to try and find the actual code that does something
8 Likes
4

There is std - Rust

1 Like
5

I’ve recently discovered https://stdrs.dev. I don’t know who made this site, but it’s mostly the internals of standard library (i.e. documented hidden+private items). Unfortunately some trait implementation listings are apparently incomplete. (I don’t know whose site this is so I don’t know who to report the issue to...) But they do have links in the generated source somehow o.O

E.g. https://stdrs.dev/nightly/x86_64-unknown-linux-gnu/src/alloc/string.rs.html#45 – yes, clickable use statements. I’m not certain whether thats a custom thing or an unstable rustdoc feature.

And now @chrisd posted the same site right before I finished my comment… xD

Edit: Somehow, I never googled the URL before. Right...

and

give some context.

4 Likes
6

Oh, sorry! I didn't know you were aware. It was posted to reddit: "Officially" announcing stdrs.dev - docs for the inner-workings of std by the person hosting it.

7

The way I found it some time this week was by googling rust sourceiter.

8

Oh, wow, I just noticed that that happens to me for locally generated documentation as well, so it might be a rustdoc bug!

9

This is great but I can feel my desire for some distinction between "unstable forever because implementation detail" and "actually 'experimental' in the sense of maybe being stable one day" ballooning already :sweat_smile:

10

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.