Skip to content
New issue

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

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

Already on GitHub? Sign in to your account

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

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in 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