Make docs more consistent #8908
Conversation
|
r? @Manishearth (rust-highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
|
I like unifying the documentation. Here we suggest using I have no real preference, which is better, but I believe that |
Serial-ATA
force-pushed
the
doc-comment-issues
branch
from
70ae87a to
adafb6c
Compare
|
r? @xFrednet since you've already had a look 😄 |
| @@ -29,7 +29,7 @@ declare_clippy_lint! { | |||
| /// if true { /* ... */ } | |||
| /// ``` | |||
| /// | |||
| /// // or | |||
| /// or | |||
There was a problem hiding this comment.
In cases with or we might want to consider removing the // bad comment and replacing the // good with // use instead instead. What do you think? And would you mind updating that in another commit?
Thinking about this a bit more, I think it's good to remove the "// bad" comments, as it can be seen as degrading the actual code. But I might also be over thinking this a bit too much 😅
There was a problem hiding this comment.
Alternatively, we could also use multiple ### Example headlines, but I believe that that would look weird 😅
There was a problem hiding this comment.
Forgot to fix this one, I just noticed the misplaced comment 😄. I think "or" should be removed entirely and all "bad" snippets should go in the same example, and all of the "good" ones in the Use instead section:
Examples
if { true } { /* ... */ }
if { let x = somefunc(); x } { /* ... */ }Use instead:
if true { /* ... */ }
let res = { let x = somefunc(); x };
if res { /* ... */ }I think that's a lot cleaner, what do you think?
There was a problem hiding this comment.
In this example, I agree 👍 . There might be some cases where this could be overwhelming, though. Could you review the other "// or" cases as well? If it's the same story, then we can just remove the "// bad" comments and separate the examples into the two blocks. :)
There was a problem hiding this comment.
All of the other occurrences look alright if they were to be combined. It doesn't seem to be that common of a pattern, and when it's used the examples are pretty short.
There was a problem hiding this comment.
Perfect. Can you combine them in this PR?
There was a problem hiding this comment.
Done. Can I replace the // Good/// Bad comments in another PR? There are too many to do at once 😄.
Serial-ATA
force-pushed
the
doc-comment-issues
branch
from
b95a7ae to
b20f95c
Compare
|
Looks good to me, thank you for the update! 👍 @bors r+ |
|
📌 Commit b20f95c has been approved by |
|
☀️ Test successful - checks-action_dev_test, checks-action_remark_test, checks-action_test |
Improve lint doc consistency changelog: none This is a continuation of #8908. Notable changes: - Removed empty `Known Problems` sections - Removed "Good"/"Bad" language (replaced with "Use instead") - Removed (and added some 😄) duplication - Ignored the [`create_dir`] example so it doesn't create `clippy_lints/foo` 😄
changelog: none
This just fixes some docs to make them more consistent. I mostly just changed
// Good,// Bad, etc toUse instead:.