Rustdoc, doctests, and private documentation

I’ve gotten into the habit of writing rustdoc even for the private items in my projects. With cargo doc --document-private-items, it yields very helpful guides for internal contributors. When I added a few example block doctests, though, I ended up stubbing my toe on a couple related corners:

  • The context of a doctest is external to the crate it is documenting, therefore private items are not visible
  • cargo test tries to build and run doctests, even in private items

This leaves me with several options, none of which are very satisfying:

  • Make the items I want to document public, even though they should not be used by downstream code
  • Mark examples in private items as ```ignore, leaving them untested and cluttering cargo test output
  • Just not write examples :persevere:

Are there some other options I should consider here?

Would it be feasible to have doctests interpreted as an internal module?

3 Likes

It does seem that it would make sense that examples for private APIs could reference other private APIs.

Since --document-private-items doesn’t show any notice of public/private items (the assumption is that the docs are rendered for internal use only), would it make sense to do the test build with every symbol exposed as public? @ doc-team

The problem is that doc tests are ran as “integration tests”, where they have access to your code as an external crate. For private items, it makes more sense for the documentation test to be a #[test] fn inline next to it.

1 Like

Do you think it makes sense to open this as an issue somewhere? I’m not sure which project it would be in; rustdoc perhaps?

1 Like

Did anyone ever come up with a solution for this or file an issue anywhere? I haven't been able to find much.

2 Likes

The way I see it, the current system pretty much isn't built for documenting private items.

This is very unfortunate, because it gives off the impression that documenting private items in Rust is discouraged (which I hope is not true, as documentation is very valuable to contributors), and therefore makes new users confused when they try to document private items.

I see it as the major problem with the tooling that Cargo provides.

The way I would imagine this to work is the following:

  • Any item visible to the module the documented item is in, would also be visible to the corresponding test.

I think, that it's not the best idea to have everything visible to a doctest. The reason for this is, that a doctest should document the thing it's attached to, not any other code, and it's almost always the case that all related code to an item is visible to it.

2 Likes

I'm looking for this too. :frowning:

I found this issue that doesn't get very far: Private doc test flag · Issue #60820 · rust-lang/rust · GitHub

Then there's this one with quite a bit of (somewhat related) discussion about getting doctests working for bin targets: Doctests don't work in bin targets, non-public items · Issue #50784 · rust-lang/rust · GitHub

Unfortunately it doesn't seem to be a very common request, so for now it looks like I'll be using ignore to keep the example even if it doesn't run.

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