docs(compilers/openapi): drop the wrong ir-design citation - #307
Open
OmarAlJarrah wants to merge 1 commit into
Open
docs(compilers/openapi): drop the wrong ir-design citation#307OmarAlJarrah wants to merge 1 commit into
OmarAlJarrah wants to merge 1 commit into
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three doc comments justified keeping
openapi.Optionswhole by citingir-design §10:compilers/openapi/options.go— "Its shape is a published contract (ir-design §10)"compilers/openapi/openapi.go(loadOptions) — "whose shape ir-design §10 fixes"compilers/openapi/internal/load/load.go(load.Options) — "whose shape is fixed by ir-design §10"docs/ir-design.md§10 is Servers — the IR'sServerstruct, its URL template and itsvariables. It says nothing about compiler options, and neither does any other section: the
document does not describe an options type under any spelling. Someone following the citation
to check the constraint lands on a struct about server URLs, and cannot tell whether the
constraint lives elsewhere or does not exist.
So the citation is dropped rather than renumbered, because there is nothing to re-point it at.
The claim it was propping up holds on its own terms and now says so directly:
openapi.Optionsis exported and
compilers.Options.FormatOptionsisany, so a caller outside the packageconstructs that exact type by field name —
optionsFromaccepts no other type.options.gogives the reason once and the other two defer to it rather than restating it, which is what
made a single wrong section number wrong in three places.
Only those three change. The four correct
ir-design §10citations (ir/server.go×2,compilers/openapi/meta.go×2) really are about servers and are left alone, so a blanketreplacement would have been wrong.
Comments only: no behaviour change, no signature change, no golden regeneration.
Note for merge order: #88 edits
nolintdirectives further downinternal/load/load.go. Thetwo changes touch different lines and are independent, but git may still report a textual
conflict in that file depending on which lands first.
Test plan
gofmt -l,go vet ./...,golangci-lint run(0 issues),go build ./...,./scripts/check-coverage.sh(100% statements, unchanged).grep -rn 'ir-design §10' --include='*.go' .now returns only the four server citations.have since moved:
## 10. Serversis atdocs/ir-design.md:1480, andgrep -n 'openapi.Options\|compiler options\|FormatOptions\|Options struct' docs/ir-design.mdis empty.
No test accompanies this. A section number that is wrong about its subject still resolves to a
real heading, so no mechanical check can tell this apart from a correct citation.
Closes #236