-
-
Notifications
You must be signed in to change notification settings - Fork 770
kernel: process: freshen comments #3452
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
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we either need to have a tool automatically wrapping comments to some maintained, specified width or you need to turn off automatic, whole file rewrapping in your editor.
It's really hard to figure out what actually changed with a lot of the doc updates, and churn for different, arbitrary line wrap setting doesn't feel worth it — here, it made what looks like some intentional formatting worse in a least one case.
I wouldn't argue with that!
I'm doing this manually. To me, the kernel crate is the most core crate to understand Tock, and it's worth having consistency in the presentation, even if that means periodic updates to the file because it is difficult to handle on each PR. I personally am willing to block PRs to the core kernel files until the comments are consistent, but I don't think that overhead is less than just doing it periodically.
I wouldn't say it's completely arbitrary, at least not within this PR, it's 80 characters like the other comments in the file. |
Anyone else have any thoughts? I think formatting comments is valuable. I also think that if the specific wrapping of a comment matters it should be in code block, since the formatting is not going to be preserved on the generated HTML docs anyway. |
My 2ct are: well-formatted docs are nice, but if something doesn't look too terrible we shouldn't necessarily feel the need to reformat it. So I don't think it's a big deal either way. To give some examples: if somethings formatted to wrap at 70 chars, it seems fine to keep it that way. If inserting a missing word pushes a comment above the 80 chars limit, I don't know whether we need to re-wrap 20 other lines because of that. I think the way we handled this previously was just fine, where people generally wouldn't re-wrap comments for minor changes, and then every once in a while or on major refactors, we'd adjust formatting. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I generally agree with Leon. For future PRs, I would prefer a two-commit approach where one commit includes the new text, and a separate commit just adjusts comment wrapping, to simplify reviewing
Add missing docs, minor clarifications.
9f683d5
to
8025009
Compare
Easy enough to do. First commit is all of the formatting changes, second commit is text changes. |
Pull Request Overview
Make formatting consistent, add missing comment docs, minor clarifications.
Testing Strategy
n/a
TODO or Help Wanted
n/a
Documentation Updated
/docs
, or no updates are required.Formatting
make prepush
.