`stdio` module description "stutters"

[Valloric]

This page: http://static.rust-lang.org/doc/master/std/io/stdio/index.html

The starting paragraph:

Non-blocking access to stdin, stdout, stderr Non-blocking access to stdin, stdout, stderr This modules provides bindings to the local [...]

The "Non-blocking access to stdin, stdout, stderr" section repeats itself and there are some periods missing.

[zslayton]

I looked into this a bit. It turns out it's actually a problem for all of the module-level documentation pages. The rustdoc comment from the mod.rs file appears to be getting pulled into the documentation page multiple times.

For other examples, see:

• std::io::pipe
• std::io::signal

I'm happy to take this issue, but I'm new to the documentation build system. Could someone point me to the template that I'd need to modify?

[zslayton]

It appears that this is only a problem for modules found in std::io, where the mod.rs file has a summary comment above each pub mod line. The summary is not-quite-verbatim repeated in the module file itself.

For example, std::io::fs has the following opening line:

Synchronous, non-blocking filesystem operations. Synchronous, non-blocking filesystem operations. Synchronous File I/O

mod.rs contains:

/// Synchronous, non-blocking filesystem operations.
pub mod fs;

and fs.rs contains:

/*! Synchronous File I/O

The mod.rs lines are inserted twice, followed by the file's summary line. The double-insertion appears to be a rustdoc bug, but the standard in the rest of libstd seems to be not having any comments above pub mod. I'm going to make a PR to remove the mod.rs comments.

Could someone more knowledgeable than I comment on the double-insert?

[sfackler]

I think rustdoc is correct to include both chunks of docs and that removing the docs from mod.rs is the right approach.

[huonw]

@sfackler it's not correct to include the /// comment 3 times though.

[zslayton]

@huonw @sfackler

It appears to include the /// comment twice, followed by the file summary once for a total of three.

[sfackler]

Oh, interesting.

[huonw]

@zslayton if you are interested in debugging this, creating a minimal example, and using -Z ast-json will print the AST as (prettified) JSON, so you can see if the compiler is passing the correct thing to rustdoc.

The collapse_docs function in librustdoc/passes.rs is probably also worth some investigation.

Other than that... I don't really know. (It'd be worth seeing if it is specific to modules, or if, e.g.,

/// foo
fn bar() {
     //! baz
}

confuses it too.)

[zslayton]

@huonw Thanks, I'll do that.

In the meantime, I'm going to make a PR to convert the comments in mod.rs to plain // comments. Then we can close out this issue.

If I can make a minimal, reproducible example of the double-insert problem, I'll open a new issue so we can track it separately.