Revert incorrect gofmt changes#352
Conversation
This partially reverts commit 5f3d8c3 gofmt made some incorrect changes to the godoc comments, which caused the documentation to be incorrect. This commit was done in v3 branch, main branch contains this commit as well, so we need to revert it even if code organization changed a lot in main branch. The previous format was using // Something is highlighted // More details about something // ********* We are now using this, that is stable against gofmt: // Something is highlighted // //<TAB>More details about something //<TAB> *********
There was a problem hiding this comment.
Pull request overview
This PR fixes corrupted godoc alignment caused by gofmt by switching affected comment blocks to the stable “blank // line + tab-indented (//\t...) preformatted” format, preserving ASCII-art/highlight alignment in documentation.
Changes:
- Reformat parser grammar production comments in
internal/libyaml/parser.gousing tab-indented preformatted blocks to keep alignment stable against gofmt. - Reformat the
WriteHandlerdoc block ininternal/libyaml/emitter.gosimilarly for stable godoc rendering.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| internal/libyaml/parser.go | Restores stable, aligned grammar/ascii-art godoc blocks by using tab-indented preformatted comment lines. |
| internal/libyaml/emitter.go | Adjusts the WriteHandler doc block formatting to be gofmt-stable (but see review comments re: content accuracy). |
Comments suppressed due to low confidence (1)
internal/libyaml/emitter.go:27
- This
@returnsdescription says the handler returns 1/0, but WriteHandler returns anerror. Please update the return documentation to describe the error semantics (e.g., nil on success, non-nil on failure).
// @returns On success, the handler should return @c 1. If the handler failed,
// the returned value should be @c 0.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // WriteHandler is called when the [Emitter] needs to flush the accumulated | ||
| // characters to the output. The handler should write @a size bytes of the | ||
| // @a buffer to the output. | ||
| // | ||
| // @param[in,out] data A pointer to an application data specified by | ||
| // @param[in,out] data A pointer to an application data specified by | ||
| // yamlEmitter.setOutput(). | ||
| // @param[in] buffer The buffer with bytes to be written. | ||
| // @param[in] size The size of the buffer. |
|
I was concerned that this might affect other open PRs presenting conflicts, but I ran it by Claude and they said there should be no conflicts. That said, I would like two other reviewers, not including me to approve this. |
colinjlacy
left a comment
colinjlacy
left a comment
There was a problem hiding this comment.
Took a minute to fully understand what was happening, but looks good
|
Thanks @colinjlacy ! I'm gonna merge this without waiting on a 2nd approval then,,, |
This partially reverts commit 5f3d8c3
gofmt made some incorrect changes to the godoc comments, which caused the documentation to be incorrect.
This commit was done in
v3branch,mainbranch contains this commit as well, so we need to revert it even if code organization changed a lot inmainbranch (files being moved and renamed ininternal/libyamlbut also methods being renamed in it)The previous format was using
We are now using this, that is stable against gofmt:
Fixes #344