Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Conversation

bradjc
Copy link
Contributor

@bradjc bradjc commented May 24, 2023

Pull Request Overview

Make formatting consistent, add missing comment docs, minor clarifications.

Testing Strategy

n/a

TODO or Help Wanted

n/a

Documentation Updated

  • Updated the relevant files in /docs, or no updates are required.

Formatting

  • Ran make prepush.

Copy link
Member

@ppannuto ppannuto left a 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.

@bradjc
Copy link
Contributor Author

bradjc commented Jun 8, 2023

I think we either need to have a tool automatically wrapping comments to some maintained, specified width

I wouldn't argue with that!

or you need to turn off automatic, whole file rewrapping in your editor.

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.

arbitrary line wrap setting

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.

@bradjc
Copy link
Contributor Author

bradjc commented Jun 16, 2023

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.

@lschuermann
Copy link
Member

Anyone else have any thoughts? I think formatting comments is valuable.

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.

lschuermann
lschuermann previously approved these changes Jun 20, 2023
hudson-ayers
hudson-ayers previously approved these changes Jun 25, 2023
Copy link
Contributor

@hudson-ayers hudson-ayers left a 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

@bradjc bradjc dismissed stale reviews from hudson-ayers and lschuermann via 8025009 June 26, 2023 13:47
@bradjc bradjc force-pushed the process-comments-2023 branch from 9f683d5 to 8025009 Compare June 26, 2023 13:47
@bradjc
Copy link
Contributor Author

bradjc commented Jun 26, 2023

Easy enough to do. First commit is all of the formatting changes, second commit is text changes.

@ppannuto ppannuto added this pull request to the merge queue Jun 29, 2023
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Jun 29, 2023
@bradjc bradjc added this pull request to the merge queue Jun 29, 2023
Merged via the queue into master with commit adb6456 Jun 29, 2023
@ppannuto ppannuto deleted the process-comments-2023 branch July 12, 2023 23:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants