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

Improve handling of inner docstring comments #103

Merged
merged 2 commits into from
Oct 17, 2024

Conversation

jaybosamiya-ms
Copy link
Collaborator

This PR fixes #102.

At a high level, this PR stops treating ///-prefixed docstring comments as comments, but as a syntactic structure of their own.

In essence, docstrings can only be used wherever an attr can be used (it might even be a subset of those cases, but handling it wherever attributes are handled should handle all important cases, since /// docstring comments are essentially syntax sugar for the #[doc(...)] attribute).

By removing it from normal comment handling, we gain more control over them, and can actually place them correctly, touching the actual code they should be touching; also we don't need to perform any of the normal comment management/manipulation code on them, since they are already all in place.

This PR does cause some minor churn around a small handful of docstring comments in our snapshotted files (see the second commit in this PR), but reading through all of them, it seems largely either acceptable, or even welcome changes (e.g., making the docstring associate with the next item, rather than with the previous item).

@jaybosamiya-ms
Copy link
Collaborator Author

jaybosamiya-ms commented Oct 10, 2024

Note to self: due to changing files in the snapshots, we should increment the minor version number, rather than patch, when we release this. Also, this will need a corresponding vstd PR.

Copy link
Contributor

@parno parno left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks reasonable to me. Thanks for the helpful comments in verus.pest. I agree that the minor changes to the snapshots seem positive or at worst neutral, so this seems like a good change.

@jaybosamiya-ms jaybosamiya-ms merged commit 4a50128 into main Oct 17, 2024
8 checks passed
@jaybosamiya-ms jaybosamiya-ms deleted the jb-fix-for-issue102 branch October 17, 2024 18:23
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.

verusfmt breaks rustdoc comments
2 participants