chore(docs): core/sdk lib.rs and IggyClient docs - #3809
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #3809 +/- ##
============================================
- Coverage 76.58% 75.02% -1.56%
Complexity 1046 1046
============================================
Files 1347 1347
Lines 171018 165645 -5373
Branches 142372 137074 -5298
============================================
- Hits 130967 124283 -6684
- Misses 36233 37241 +1008
- Partials 3818 4121 +303
🚀 New features to boost your workflow:
|
|
/ready |
haubur
changed the title
| //! **This library is the Apache Iggy SDK.** | ||
| //! It exposes a low-level and a high-level API for the Apache Iggy message streaming infrastructure for the Rust programming language. | ||
| //! SDKs for other programming languages can be found in [`core/foreign`] of the root repository on GitHub. | ||
| //! Note, most of them wrap this SDK. Hence, newer features might be delayed in other languages. |
There was a problem hiding this comment.
This line does not seem required here.
| //! The core of the Iggy server is a persisted append-only log data structure. | ||
| //! It is concerned with allowing read and writes in the most efficient way. | ||
| //! Reading and writing to the server is the domain of this SDK. | ||
| //! The server exposes *commands* that can be triggered to change it's state. |
There was a problem hiding this comment.
"that can be triggered to change it's state." -> "that can be triggered to change its state."
| //! The server exposes *commands* that can be triggered to change it's state. | ||
| //! These commands allow administrative tasks, such as handling users, permissions and setting up streams and topics | ||
| //! or writing and reading messages from the log. | ||
| //! A comprehensive overview of commands can be found in the [`schema spec`] on the website or checking the [`server command enum`] within the source code. |
There was a problem hiding this comment.
I think it would be better to also give links here. "schema spec" and "server command enum" do not help the reader understand where the information is located.
| //! speak the wire protocol directly and that the high-level API is built on top of. | ||
| //! Start with the high-level API unless you have a specific reason not to. |
There was a problem hiding this comment.
"Start with the high-level API unless you have a specific reason not to." -> "It is recommended to start with the high-level API, and utilize the low level API in case the high-level API cannot satisfy your requirements.
| //! Clients provided by the high-level API already provide common message-streaming features, that | ||
| //! you would otherwise need to build yourself. |
There was a problem hiding this comment.
"common message-streaming features, that" -> "common message-streaming features that"
| //! - **Auto-join** of consumer groups, assignment refresh and reconnection | ||
| //! handling, and payload **decryption**. |
There was a problem hiding this comment.
Rephrasing this would be better, difficult to understand.
| //! The stream builder API is a convenient way to use the high-level API. | ||
| //! [`IggyStream`], [`IggyStreamProducer`], and | ||
| //! [`IggyStreamConsumer`] are construct everything at once. |
There was a problem hiding this comment.
Did not understand what you're trying to convey here.
| //! construction, drop down to [`IggyClient::producer`] and | ||
| //! [`IggyClient::consumer`] and configure the builders directly. The stream |
There was a problem hiding this comment.
"drop down to [IggyClient::producer] and [IggyClient::consumer] and configure the builders directly" -> "the usage of [IggyClient::producer] and [IggyClient::consumer] is recommended"
| //! builder offers nothing the high-level API cannot, since it is built entirely | ||
| //! on top of it. |
There was a problem hiding this comment.
Would be better to replace this negative sentence with a positive one
There was a problem hiding this comment.
There seems to be a lot of repetition of stuff here. Would be better to dedupe.
github-actions
Bot
added
S-waiting-on-author
2 participants
Draft PR as discussed here: https://discord.com/channels/1144142576266530928/1144142825630474360/1507361396382240839
Would be nice to get some feedback on:
If the general direction is good and supported, happy to clean and merge.
Would suggest to continue with IggyConsumer and IggyProducer in a next PR.
Which issue does this PR address?
Closes #3306
Rationale
Adding User facing docs for the Rust SDK.
What changed?
Local Execution
AI Usage
Everything is manually written or at least re-written in cases I had claude suggest a formulation.