Make all code block of the documentation of a single item share the same scope

[robinmoussu]

Describe the problem you are trying to solve When documenting a single item, if there is more than one code-block, compile and run (with cargo test) all snippets at once. This way, it become possible to share variable between multiple blocks. It think it would be useful when:

• you have something long (and boring) to set-up, like a small graph, and want re-use it.

/// Common setup:
/// ```
/// use ...
/// let graph = create_graph();
/// let a = graph.add_node();
/// let b = graph.add_node();
/// let c = graph.add_node();
/// ```
/// First use-case:
/// ```
/// foo(graph, a, true);
/// ```
/// Second use-case:
/// ```
/// foo(graph, b, false);
/// ```
pub fn foo(graph: G, node: G::node, b: bool);

• you have a multi-part algorithm, and you want to use regular text instead of comments to explain it.

//// First create a foo
/// ```
/// let foo = create_foo()
/// ```
/// Then pass it to bar, with a frob transformation:
/// ```
/// bar(foo, add_frob())
/// ```

Describe the solution you'd like

I see two possible solution.

• Either all snippet documenting a single item would share the same scope automatically. It requires no modification from the user (and would be the easier to use. But I don't know if it can break existing tests (due to the ? operator most probably).
• Or manually, with an annotation after the ```, For example ```extend_scope.

Notes I am not fully certain that this feature request should be done here, or in rustc itself. Please tell me if I need to report it elsewhere.

[ehuss]

This is an issue for rustdoc, so I have moved it to the rust-lang/rust repo where it lives.

[robinmoussu]

Thanks

[Mark-Simulacrum]

You can comment out lines in code blocks by prefixing with #. I think beyond that, this would be significantly backwards incompatible, so we could only do it on an edition boundary (and even there it's a bit hard), or, as you suggest with an attribute.

I personally feel like it could be hard to get the UI right for this in the rendered documentation - though it seems like that's already true for the comments, to some extent.

[robinmoussu]

You can comment out lines in code blocks by prefixing with #.

That's right, but it would clutter the code source a lot, as well as making it harder to maintain.

I think beyond that, this would be significantly backwards incompatible, so we could only do it on an edition boundary (and even there it's a bit hard), or, as you suggest with an attribute.

I really think that backward compatibility is really important for this, so using an attribute seems a much better idea.

I personally feel like it could be hard to get the UI right for this in the rendered documentation - though it seems like that's already true for the comments, to some extent.

What do you mean by that?

[Mark-Simulacrum]

We currently try to highlight whether a code block compiles or not in the UI. I think this particular request is getting into the territory of literate programming, which rustdoc's UI IMO is not particularly well suited for. I suspect that there's a sufficient amount of toggles you'd eventually reach where rustdoc at some point is just the wrong tool for the job. I suspect that for this request in particular developing an out-of-tree macro that gets applied to code blocks may be the better approach; I think that this feature is sufficiently niche that I'm not sure it should be in core rustdoc.

[robinmoussu]

I have another idea. Triple slash in documentation comment could be interpreted as regular documentation.

/// Some documentation
/// ```
/// let some_code = 0;
/// // some comment
/// /// # A title
/// /// More  documentation
/// let other_code = some_code;
/// ```
pub fn foo();

Would be displayed as:

----------------------------------------------------------------------------------------

Function

fn foo()

---

Some documentation

let some_code = 0;
// some_comment

A title

More documentation

let other_code = some_code;

---------------------------------------------------------------------------------------- Instead of the current ----------------------------------------------------------------------------------------

Function

fn foo()

---

Some documentation

let some_code = 0;
// some_comment
/// /// # A title
/// More documentation
let other_code = some_code;

----------------------------------------------------------------------------------------

Do you think it is something that could be accepted if I did the work to implement it?

[Mark-Simulacrum]

I believe that any change here would need to follow the RFC process, given the number of possible options. However, opening a thread on internals and proposing your ideas would be viable. I think this is a sufficiently major feature that keeping track of it on this issue tracker (intended for bugs, mostly) isn't a good fit, there's not going to be enough eyes on it here for proper feedback.

[robinmoussu]

Thanks, I will do as you said.

[robinmoussu]

For information, I opened it here