How to write a doc that's incomplete / failed intentionally?

I know one of the main Rust feature is built-in documentation testing. You can write any comment like this and it will be available on generated documentation. But how do you create a comment that incomplete / cannot run ?

    /// ## Foo Function 
    /// Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    /// Duis eleifend at dolor auctor maximus. Vestibulum 
    /// ### How to use
    /// ```
    /// use quikserver::Item;
    /// Item::map_from_doc(&foo) <---- this error on test since I do not declare `foo` 
    /// ```
    pub fn foo_func(doc: &str) -> Result<Self, ItemError> {...}

I do not want to write the entire code for foo variable. I just want to give user a simple explanation about the function usage. I think that there should be a way to skip document testing on this part.

So far I can only found about hiding parts of the code, which means that I need to write the complete example code and hide some of it. Documentation tests - The rustdoc book

How to write a doc that's incomplete / failed intentionally ?

```ignore
code
```
Or perhaps compile_fail.

1 Like

Another version of this is to make it compile, but mark it no_run and make it a fake value.

Perhaps something like this:

    /// ```no_run
    /// use quikserver::Item;
    /// # let foo = panic!();
    /// Item::map_from_doc(&foo);
    /// ```

so that you can make it compile, and thus check for typos, but not have to make a fully legal example.

2 Likes

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.