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

Question

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.

I *think* you have to add `ignore` after the first three backticks. — Lukas Kalbertodt, Feb 20 '17 at 15:21
@Shepmaster Because there is no `myValue` (Could be fixed in this example by adding a let). What I need it for is to use an associated method of a trait on a type which I do not want to show in the documentation because it is not restricted to that one. — torkleyy, Feb 20 '17 at 15:22
@LukasKalbertodt no cargo just won't run it then except you use something like --all — torkleyy, Feb 20 '17 at 15:23
Related question: http://stackoverflow.com/questions/40550665 — ideasman42, Feb 22 '17 at 07:54

score 14 · Accepted Answer · edited Aug 16 '20 at 18:57

14

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);
/// ```

edited Aug 16 '20 at 18:57

Ross MacArthur

4,735
1
24
36

answered Feb 20 '17 at 15:21

Chris Emerson

13,041
3
44
66

The code will still be compiled, so the test will fail – torkleyy Feb 20 '17 at 15:29
With ignore, or no_run? – Chris Emerson Feb 20 '17 at 15:32
with `no_run`; `ignore` isn't a perfect solution, because it is for tests which are too expensive but can be run when appropriate – torkleyy Feb 20 '17 at 15:34
How about just a comment? – Chris Emerson Feb 20 '17 at 15:43
The link is not correct anymore and I didn't find where it's written now. – Stargateur Jul 09 '19 at 16:57

score 6 · Answer 2 · edited Feb 20 '17 at 15:29

6

If you want to ignore a part of Rust code in doctests, you might want to read the section on running documentation tests. Basically extract that code into a different block and set that block to rust,ignore.

This will ignore IGNORE_FOR_COMPILATION_BUT_SHOW completely, but the rest will run:

///```rust,ignore
///IGNORE_FOR_COMPILATION_BUT_SHOW: let cloned = myValue.clone(); 
///```

///```rust
/// # let cloned = 5.clone();
/// ```

If you want rustdoc to compile your doc tests, but not run it, you can use rust,no_run

edited Feb 20 '17 at 15:29

Shepmaster

388,571
95
1,107
1,366

answered Feb 20 '17 at 15:21

Daniel Fath

16,453
7
47
82

Is there also a way to run it? So to run every line except the ignored one? – torkleyy Feb 20 '17 at 15:25
3

You can create several blocks, some ignored, some running normally. They are always displayed, they just don't run etc. – Daniel Fath Feb 20 '17 at 15:25

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

Examples

2 Answers2