Skip to content

Doc comments with code at beginning includes all of code in doc output #54975

New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Closed
Munksgaard opened this issue Oct 10, 2018 · 1 comment
Closed
Assignees
Labels
T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@Munksgaard
Copy link
Contributor

Putting code at the top of a docstring results in the entire code bit being included in the short summary of the docstring.

The following code

/// ```
/// foo
/// bar
/// ```
pub struct Foo;

Results in the following foo/index.html page

bla

Having large code samples there generates ugly documentation. For instance, I ran across the following while working through #54824 (in src/test/rustdoc/issue-47183.rs)

bla2

Which is generated by the following code:

/// ```no_run
/// # # space
/// # comment
/// ## single
/// ### double
/// #### triple
/// ##[outer]
/// ##![inner]
/// ```
pub struct Foo;

My suggestion would be that rustdoc should detect whether the first line of a doc comment is the beginning of a code block, and if so, it should leave it out of the "preview".

@Havvy Havvy added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Oct 10, 2018
@GuillaumeGomez
Copy link
Member

GuillaumeGomez commented Oct 13, 2018

Makes sense. I'll send a patch as soon as possible.

@GuillaumeGomez GuillaumeGomez self-assigned this Oct 13, 2018
kennytm added a commit to kennytm/rust that referenced this issue Nov 13, 2018
…sdreavus

Remove short doc where it starts with a codeblock

Fixes rust-lang#54975.
# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

3 participants