Hide part of the documentation

help
1

I would like to hide only part of the documentation of a module or element.
Is there a compilation or rustdoc flag that can be used?

Motivation

Turn on and off part of the documentation. For example,

  • Implementation section, explaining the inner implementation.
  • Literate programming style documentation through the code to explain why the code is written as it is.

Current solutions

  • Use the details HTML tag in the documentation.

Example

/// A public struct.
#[cfg(feature = "implementation")]
/// # Implementation
/// This is a private documentation section
pub struct Public; // This is a public struct included without any feature

Current solution

/// A public struct.
/// <details>
/// <summary>Implementation</summary>
/// <p>This is a private documentation section</p>
/// </details>
pub struct Public;
2

I've used the \internal command in doxygen extensively over the years, and I really miss the functionality in rustdoc. It is possible to emulate it, using this technique, but it is kind of verbose (compared to the \internal command in doxygen). That said, the rustdoc way to do it has its upsides (like how you can add sections that depend on other features as well).

3

It's not quite what you are looking for because you can't keep the implementation docs next to Public's definition, but you could combine #[cfg_attr] and the fact that you can do #[doc = include_str!("...")] to conditionally include detailed docs from an external file.

// A public struct.
#[cfg_attr(feature = "implementation", doc = include_str!("./public.md"))]
pub struct Public;
4

I'd say the most common way is to use "normal" comments

/// A public struct.
#[cfg(feature = "implementation")]
// # Implementation
// This is a private documentation section
pub struct Public; // This is a public struct included without any feature
5

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.