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

Fix formatting crosstalk #1317

Merged
merged 3 commits into from Sep 6, 2022

Conversation

MrDOS
Copy link
Contributor

@MrDOS MrDOS commented Sep 5, 2022

Describe the PR

Fixes formatting crosstalk (#1314) by modelling and applying formatting changes as byte-range edits rather than find/replace operations, which could accidentally clobber identical (correctly-formatted) comment lines.

Relation issue

Resolves #1314.

Additional comments

Of course, everyone's experience will vary, but in the codebase I'm working in with – 4,132 attribute comments across 450 comment groups – this fix changes 8 comment lines. Those changes are pretty obvious and desirable, but I also don't anticipate that this will generate huge waves of changes in existing codebases.

The previous find-and-replace technique for replacing comment lines with
their formatted counterparts could apply the change to the wrong line,
when multiple identical comment lines exited. This led to “crosstalk”: a
formatting change to a comment on one function being applied to another,
unrelated function. By modeling each desired replacement with the byte
range that it specifically applies to, replacements are now always made
to the desired location.
@MrDOS MrDOS mentioned this pull request Sep 5, 2022
@codecov
Copy link

codecov bot commented Sep 6, 2022

Codecov Report

Merging #1317 (21e660d) into master (e7ccdf4) will increase coverage by 0.01%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master    #1317      +/-   ##
==========================================
+ Coverage   95.61%   95.63%   +0.01%     
==========================================
  Files          14       14              
  Lines        2851     2863      +12     
==========================================
+ Hits         2726     2738      +12     
  Misses         70       70              
  Partials       55       55              
Impacted Files Coverage Δ
formatter.go 100.00% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

Copy link
Contributor

@ubogdan ubogdan left a comment

Choose a reason for hiding this comment

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

Please update according to my comments if you like to see some performance in a large code base.

formatter.go Outdated Show resolved Hide resolved
formatter.go Outdated Show resolved Hide resolved
formatter.go Outdated Show resolved Hide resolved
formatter.go Outdated Show resolved Hide resolved
@MrDOS MrDOS force-pushed the bugfix/fix-formatting-crosstalk branch 2 times, most recently from 9faee27 to 21e660d Compare September 6, 2022 11:07
@MrDOS
Copy link
Contributor Author

MrDOS commented Sep 6, 2022

Thanks for the feedback. I've changed things around to preallocate the edit list.

swag/formatter.go

Lines 62 to 66 in 21e660d

maxEdits := 0
for _, comment := range ast.Comments {
maxEdits += len(comment.List)
}
edits := make(edits, 0, maxEdits)

I couldn't make the exact edits you asked for, as the outer edit list may contain up to as many entries as there are comment lines, but probably won't: there will likely be comment lines that don't contain Swag attributes, and we don't create edit entries for those. Also, allocating this with

edits := make(edits, 0, len(ast.Comments))

would only allocate space for one edit per group.

Instead of allocating this slice with its size as the maximum possible number of entries, I'm instead allocating it with the maximum necessary capacity, and a size of 0. This lets me use append normally to gradually grow the size of the slice but without requiring further allocations. That way, I don't need to separately keep track of how many things I've put into the slice – the slice's natural size tracks that for me.

func formatFuncDoc(fileSet *token.FileSet, commentList []*ast.Comment, edits *edits) {

Instead of allocating another edit list inside the formatting function, I'm now just passing in the overall edit list and appending to it directly. This removes the need to allocate a temporary slice of edits per comment group.

@MrDOS MrDOS requested a review from ubogdan September 6, 2022 11:32
@ubogdan
Copy link
Contributor

ubogdan commented Sep 6, 2022

@MrDOS You're welcome. Your last implementation looks even better.

Copy link
Contributor

@ubogdan ubogdan left a comment

Choose a reason for hiding this comment

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

LGTM

@ubogdan ubogdan merged commit bc895ed into swaggo:master Sep 6, 2022
@ubogdan
Copy link
Contributor

ubogdan commented Sep 6, 2022

@MrDOS Thanks for your contribution.

@MrDOS MrDOS deleted the bugfix/fix-formatting-crosstalk branch September 7, 2022 23:21
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.

Formatting crosstalk
2 participants