Skip to content

docs: README accuracy and structure pass - #13

Closed
embeddinglayer wants to merge 1 commit into
mainfrom
docs/readme-polish
Closed

embeddinglayer wants to merge 1 commit into
mainfrom
docs/readme-polish

Conversation

@embeddinglayer

Copy link
Copy Markdown
Contributor

Every claim and example in the README was checked against the source. Nothing was wrong, so this is a restructure plus a few additions; existing wording is kept and only moved.

Structure

  • Sections follow the order shared by the other SDK READMEs: Installation, Quick Start, Authentication (with API Keys), Available Resources and Operations, IP and Domain Lookups, Account, Feeds (Streaming, Pagination, Downloads), Errors, Retries and Timeouts, Configuration (Server Selection, Custom HTTP Client), Response Metadata, gRPC Schema, Requirements, Versioning, Documentation, Contributions, License.
  • Renamed: SDK Installation -> Installation, Error Handling -> Errors, Debugging -> Response Metadata, Maturity -> Versioning. The # Development heading is gone.
  • The feed table moved from the method list into the new Feeds section, so #feeds has one target. The method list's heading is now Feed, the class name.

Added (all from the source)

  • Lookups: non-literal addresses throw before a request; empty and oversized batches; lookupDomain(domain) default of 50 events and the 1000 clamp; Punycode.
  • Account: health().
  • Pagination: listExports() default page size of 100, the 500 maximum, allExports(limit, cursor).
  • Retries: backoff from one second up to 30 seconds; a Retry-After over one minute is not retried.
  • Timeouts: the 10 second connect timeout.
  • Configuration: a table of the builder options and their defaults; what close() does.
  • Response Metadata: the hook runs on the calling thread; rateLimit() can be null; storage downloads are not reported.
  • gRPC Schema: FetchOptions (endpoint, symbols, plaintext, 30 second deadline), Schema.endpoint()/symbols(), SchemaException.code().
  • Links from each section to the matching page on docs.synthient.com, and a Documentation section.

Not verifiable from this repo (left as written)

  • Server-side behaviour: which scope covers which endpoint (BASIC), credit pricing, the 30 minute stream lifetime, the 15 second keepalive, the 00:30 UTC rollup, the meaning of each status code.
  • That the javadoc.io deep links resolve.

Copilot AI balanced review requested due to automatic review settings November 15, 2026 22:32

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Note

Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

🟡 Changes recommended

A documentation nit remains unresolved: the README contains a grammatically incomplete link text ("gRPC schema artifact's") that reads like a typo, so the change should be corrected before approval.

1 open issue
What changed in this PR

Reorganizes and refines the SDK README to align with the standard structure used across other SDKs, while adding source-backed clarifications and improving navigability.

Changes:

  • Reordered and renamed README sections to a consistent SDK-wide layout and updated the table of contents.
  • Added verified details for lookups, account health, feed pagination/downloads, retries/timeouts, configuration defaults, response metadata, and gRPC schema usage.
  • Added cross-links to docs.synthient.com and a consolidated Documentation section.
File Description
README.md Restructures the README to a standardized section order, adds source-derived behavioral details and defaults, and improves navigation with cross-links and expanded documentation.

Review effort: Balanced

Comment thread README.md
## Documentation

- [Java SDK guide](https://docs.synthient.com/sdks/java): [client](https://docs.synthient.com/sdks/java/client), [lookups](https://docs.synthient.com/sdks/java/lookups), [feeds](https://docs.synthient.com/sdks/java/feeds), [errors and retries](https://docs.synthient.com/sdks/java/errors), [types](https://docs.synthient.com/sdks/java/types), and [gRPC schema](https://docs.synthient.com/sdks/java/grpc-schema)
- [Javadoc](https://javadoc.io/doc/com.synthient/synthient-java), and the [gRPC schema artifact's](https://javadoc.io/doc/com.synthient/synthient-java-grpcschema)
@embeddinglayer
embeddinglayer deleted the docs/readme-polish branch November 15, 2026 23:07
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.

2 participants