documentationrustrust-cargorustdoc

How to put a line into the documentation which is ignored for doc tests?


How can I write a line into the documenation code but let the compiler ignore it?

I want to write

/// # Examples
///
/// To clone something, do
///
/// ```
/// IGNORE_FOR_COMPILATION_BUT_SHOW: let cloned = myValue.clone();
/// # let cloned = 5.clone();
/// ```

And I want to get:

Examples

To clone somthing, do

let cloned = myValue.clone();

But the compiler should still compile the example (cloning the 5).

EDIT: I also want cargo to run the example, but leave out one line.


Solution

  • The documentation says you can do this:

    /// ```rust,ignore
    /// highlighted as rust code but ignored by rustdoc
    /// ```
    

    There is also rust,no_run which compiles but doesn't run the example code.

    Alternatively, you could use the same solution as you would in ordinary code: comment it out.

    /// ```rust
    /// let x=5;
    /// // x = 6;  // won't be run
    /// assert_eq!(x, 5);
    /// ```