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

rustdoc: insert blank lines between consecutive doc comment blocks #6757

Closed
wants to merge 1 commit into from

Conversation

ben0x539
Copy link
Contributor

This is to prevent, for example,

/**
 * foo
 */

/// bar

mod m {
  //! baz
}

from being rendered into a single paragraph "foo bar baz" in the html.

This is to prevent, for example,

    /**
     * foo
     */

    /// bar

    mod m {
      //! baz
    }

from being rendered into a single paragraph "foo bar baz" in the html.
@ben0x539
Copy link
Contributor Author

Changing strip_doc_comment_decoration() to also return an enum representing the type of doc comment it was seemed like the path of least resistance here, but rustdoc having to be aware of the different kinds of lexical syntaxes of doc attributes isn't really all that elegant. The approach of modifying the lexer or the parser to merge multiple line comments into one doc attribute so that rustdoc could just emit blank lines between any two doc attributes wasn't popular in #rust at all though. Thoughts?

@bstrie
Copy link
Contributor

bstrie commented May 27, 2013

This actually raises a good point... I have no idea what should be happening in the code above. IMO having more than one doc comment (let alone more than one kind of doc comment) on any given item could only be an error (e.g. deleting a function but forgetting to delete its preceding comment). Should this even be legal?

@ben0x539
Copy link
Contributor Author

Maybe not! I went for a mostly-behavior-preserving fix to a hypothetical formatting issue here, no one seems to use multiple kinds of doc comments right now. I wouldn't mind seeing them gone. Rustdoc could just fail instead of emitting a blank line here, or multiple blocks of doc comments could a proper syntax error (though allowing for multiple ///-comments hopefully).

Though if you want to save users from mistakes like the following, it'd almost have to be a lexer thing?

/// old irrelevant doc comment
// <deleted pub fn f() {} was here>

/// multiple doc line-comments go here, forming
/// a single paragraph of the documentation, etc
pub fn g() {}

@bstrie
Copy link
Contributor

bstrie commented May 28, 2013

I'd like to have someone else weigh in on this. In the meantime I've filed #6781 and #6782 , which could potentially obsolete this.

@graydon graydon closed this Jun 13, 2013
flip1995 pushed a commit to flip1995/rust that referenced this pull request Feb 25, 2021
Quick fix cargo dev bless

fixes rust-lang#6757
r? `@phansch`

Trying to do a quick fix of `bless`, I'm not sure how much work it will need to do transition to `bless` built in `compiletest`, so please feel free to close this PR if it will not need so much.

changelog: none
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants