Rustdoc and internals

In doxygen it is possible to mark sections of the documentation as "internal". When generating the documentation one can choose to include internal information or not. (There's some overlap with --document-private-items, but it's not really the same).

With doxygen one can do this sort of thing:

/// A greeting function.
///
/// \internal
/// The semantics of the greeting is blah, blah, blah..
/// (This part is only included if one explicitly requests it to be,
/// like with --document-private-items)
/// \endinternal
fn hello() {
  // ...
}

Is it possible to accomplish this sort of thing with rustdoc?

Sorry, it's not.

You're going to need to write up an RFC for this if you want it.

You can sort of emulate that function. Doc comments are really just attributes of the form #[doc = "..."]. Since they are attributes, they can be enabled conditionally using #[cfg_attr(..)]. You can introduce a feature, let's say "internal_doc", and guard all doc comments on that feature:

#[cfg_attr(feature = "internal_doc", doc = "...")]

If you enable the feature in rustdoc as cargo doc --features internal_doc, the extra documentation will be included. It will be omitted otherwise.

I imagine you can do a similar thing using environment variables and setting cfg options in build.rs, if you don't want to hijack the feature mechanism.

Granted, it's not pretty to write. Part of that can be alleviated using some simple proc macro, which would take e.g. a sequence of strings representing the lines of doc comment, and output the corresponding sequence of gated doc attributes.

Proper support for that feature would indeed require an RFC, with a good motivational use case.

3 Likes

Indeed, I'm wondering: how would this differ from documentation on private items at all?