docs: fix inaccurate examples and add architecture diagrams#6
Merged
Conversation
The README and package documentation contained code snippets that did not
compile or referenced APIs that do not exist. This corrects them against the
actual public API and adds Mermaid diagrams to explain the design.
README.md:
- Fix broken snippets (stray `httpx.)` fragments, `WithWithMethodGET` typos)
- Correct method names to the real API: WithMethod (not HTTPMethod),
WithContext (not Context), WithQueryParams/WithHeaders/WithRawBody/
WithBytesBody (not QueryParams/Headers/RawBody/BytesBody)
- Remove references to methods that do not exist (GetBaseURL,
GetDefaultHeaders) and to features the client does not provide
("base URL resolution", "default headers applied to all requests")
- Use full URLs in GenericClient.Get examples (relative paths are not
supported by the convenience methods)
- Document previously-undocumented options: WithProxy, WithLogger,
WithRetryStrategyAsString, and the NewHTTPRetryClient family
- Add an mocking example leveraging the HTTPClient interface
- Add Mermaid diagrams: component overview, request lifecycle sequence,
composition model, error-accumulation flow, retry decision flow, and a
backoff-strategy comparison chart
docs.go (package doc):
- Same broken-snippet and method-name fixes as the README
- Use full URLs and `any` instead of `interface{}` per project style
No source-behavior changes; go build, go vet, gofmt, and go test all pass.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
1 participant
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
While reviewing the public documentation I found that many code snippets in the README and package doc (
docs.go) did not compile or referenced APIs that don't exist. This PR corrects everything against the actual public API and adds Mermaid diagrams so users can understand the design at a glance.No source behavior changes — docs only.
go build,go vet,gofmt -l, andgo test ./...(89%+ coverage) all pass.What was wrong (and is now fixed)
Verified against the real exported API:
builder.HTTPMethod("")WithMethod.Context(ctx),.QueryParams(...),.Headers(...),.RawBody(...),.BytesBody(...)WithContext,WithQueryParams,WithHeaders,WithRawBody,WithBytesBody.Path(...),.Header(...),.BearerAuth(...),.JSONBody(...),.ContentType(...)(bare, indocs.go)With…client.GetBaseURL(),client.GetDefaultHeaders()Get/Post/…take a full URLWithWithMethodGET()typos, strayhttpx.)/httpx.//fragmentsclient.Get("/users/1")(relative)Also documented options that existed but were missing from the docs:
WithProxy,WithLogger,WithRetryStrategyAsString, and the wholeNewHTTPRetryClientfamily (WithMaxRetriesRetry,WithRetryStrategyRetry,WithBaseTransport,WithProxyRetry,WithLoggerRetry).Diagrams added (Mermaid, render natively on GitHub)
RequestBuilder,GenericClient[T],ClientBuilder, and the retry transport compose overnet/http503→ retry →200HTTPClient)Other improvements
example_*_test.goto what it demonstratesHTTPClientinterfaceRequestBuilderis not concurrency-safe; clients are)MaxIdleConnsPerHost,ExpectContinueTimeout)Test plan
go build ./...go vet ./...gofmt -lcleango test ./...passes (coverage 89.3%)🤖 Generated with Claude Code