docs: s2::client (#121)

Signed-off-by: Vaibhav Rabber <[email protected]>

src/client.rs

@@ -1,4 +1,35 @@
 //! SDK client implementation.
+//!
+//! The module defines three clients:
+//!
+//! |                  | Operations               | API Service      |
+//! |------------------|--------------------------|------------------|
+//! | [`Client`]       | Account level operations | [AccountService] |
+//! | [`BasinClient`]  | Basin level operations   | [BasinService]   |
+//! | [`StreamClient`] | Stream level operations  | [StreamService]  |
+//!
+//! To interact with any client, you need an authentication token which can be
+//! generated by the the web console at [s2.dev]. This token is passed to the
+//! client via a [`ClientConfig`].
+//!
+//! Along with the authentication token, a [`ClientConfig`] defines other
+//! request parameters such as timeouts, S2 endpoints, etc.
+//!
+//! A client can be created using the corresponding `new()` method. To avoid
+//! creating multiple connections to each service, [`Client::basin_client`] can be
+//! used to create a [`BasinClient`] and [`BasinClient::stream_client`] can be
+//! used to create a [`StreamClient`].
+//!
+//! **Note:** Even though the client creation operation is cheap, a
+//! [`BasinClient`] should preferably be stored instead of using
+//! [`Client::basin_client`] multiple times as the account endpoint might vary
+//! from the basin endpoint creating a new connection each time the request is
+//! sent. See [`S2Endpoints`].
+//!
+//! [AccountService]: https://s2.dev/docs/interface/grpc-api#accountservice
+//! [BasinService]: https://s2.dev/docs/interface/grpc-api#basinservice
+//! [StreamService]: https://s2.dev/docs/interface/grpc-api#streamservice
+//! [s2.dev]: https://s2.dev/dashboard
 
 use std::{env::VarError, fmt::Display, str::FromStr, time::Duration};