Skip to content

docs(compilers/openapi): drop the wrong ir-design citation - #307

Open
OmarAlJarrah wants to merge 1 commit into
mainfrom
docs/openapi-options-citation
Open

docs(compilers/openapi): drop the wrong ir-design citation#307
OmarAlJarrah wants to merge 1 commit into
mainfrom
docs/openapi-options-citation

Conversation

@OmarAlJarrah

Copy link
Copy Markdown
Member

Summary

Three doc comments justified keeping openapi.Options whole by citing ir-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's Server struct, its URL template and its
variables. 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.Options
is exported and compilers.Options.FormatOptions is any, so a caller outside the package
constructs that exact type by field name — optionsFrom accepts no other type. options.go
gives 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 §10 citations (ir/server.go ×2,
compilers/openapi/meta.go ×2) really are about servers and are left alone, so a blanket
replacement would have been wrong.

Comments only: no behaviour change, no signature change, no golden regeneration.

Note for merge order: #88 edits nolint directives further down internal/load/load.go. The
two 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

  • Full gate clean: 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.
  • Checked against the doc as it stands rather than the line numbers quoted in the issue, which
    have since moved: ## 10. Servers is at docs/ir-design.md:1480, and
    grep -n 'openapi.Options\|compiler options\|FormatOptions\|Options struct' docs/ir-design.md
    is 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

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.

openapi: three doc comments cite ir-design §10 as fixing the Options shape; §10 is Servers

1 participant