doc comment updates

Author: analogrelay

sdk/cosmosdb/azure_data_cosmos/Cargo.toml

@@ -34,4 +34,10 @@ clap.workspace = true
 workspace = true
 
 [features]
+default = ["hmac_rust"]
+hmac_rust = ["azure_core/hmac_rust"]
+hmac_openssl = ["azure_core/hmac_openssl"]
 key-auth = [] # Enables support for key-based authentication (Primary Keys and Resource Tokens)
+
+[package.metadata.docs.rs]
+features = ["key-auth"]

sdk/cosmosdb/azure_data_cosmos/README.md

@@ -1,5 +1,5 @@
-# azure_data_cosmos
+# Azure Cosmos DB SDK for Rust.
 
-Azure Cosmos DB Rust SDK.
+## Introduction
 
-License: MIT
+This client library enables client applications to connect to [Azure Cosmos DB](https://azure.microsoft.com/en-us/products/cosmos-db) via the NoSQL API. Azure Cosmos DB is a globally distributed, multi-model database service.

sdk/cosmosdb/azure_data_cosmos/examples/cosmosdb_connect.rs

@@ -31,7 +31,7 @@ pub async fn main() -> Result<(), Box<dyn std::error::Error>> {
 #[cfg(feature = "key-auth")]
 fn create_client(args: &Args) -> CosmosClient {
     if let Some(key) = args.key.as_ref() {
-        CosmosClient::with_shared_key(&args.endpoint, key.clone(), None).unwrap()
+        CosmosClient::with_key(&args.endpoint, key.clone(), None).unwrap()
     } else {
         let cred = azure_identity::create_default_credential().unwrap();
         CosmosClient::new(&args.endpoint, cred, None).unwrap()

sdk/cosmosdb/azure_data_cosmos/src/clients/cosmos_client.rs

@@ -28,6 +28,21 @@ pub trait CosmosClientMethods {
 
 impl CosmosClient {
     /// Creates a new CosmosClient, using Entra ID authentication.
+    ///
+    /// # Arguments
+    ///
+    /// * `endpoint` - The full URL of the Cosmos DB account, for example `https://myaccount.documents.azure.com/`.
+    /// * `credential` - An implementation of [`TokenCredential`](azure_core::auth::TokenCredential) that can provide an Entra ID token to use when authenticating.
+    /// * `options` - Optional configuration for the client.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// use azure_data_cosmos::CosmosClient;
+    ///
+    /// let credential = azure_identity::create_default_credential().unwrap();
+    /// let client = CosmosClient::new("https://myaccount.documents.azure.com/", credential, None).unwrap();
+    /// ```
     pub fn new(
         endpoint: impl AsRef<str>,
         credential: Arc<dyn TokenCredential>,
@@ -44,9 +59,21 @@ impl CosmosClient {
         })
     }
 
-    /// Creates a new CosmosClient, using shared key authentication.
+    /// Creates a new CosmosClient, using key authentication.
+    ///
+    /// # Arguments
+    ///
+    /// * `endpoint` - The full URL of the Cosmos DB account, for example `https://myaccount.documents.azure.com/`.
+    /// * `key` - The key to use when authenticating.
+    /// * `options` - Optional configuration for the client.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// let client = CosmosClient::with_shared_key("https://myaccount.documents.azure.com/", "my_key", None)?;
+    /// ```
     #[cfg(feature = "key-auth")]
-    pub fn with_shared_key(
+    pub fn with_key(
         endpoint: impl AsRef<str>,
         key: impl Into<Secret>,
         options: Option<CosmosClientOptions>,

sdk/cosmosdb/azure_data_cosmos/src/clients/database_client.rs

@@ -4,13 +4,44 @@ use crate::{CosmosClient, ReadDatabaseOptions};
 use azure_core::{Context, Request};
 use url::Url;
 
+#[cfg(doc)]
+use crate::CosmosClientMethods;
+
+/// Defines the methods provided by a [`DatabaseClient`]
+///
+/// This trait is intended to allow you to mock out the `DatabaseClient` when testing your application.
+/// Rather than depending on `DatabaseClient`, you can depend on a generic parameter constrained by this trait, or an `impl DatabaseClientMethods` type.
 pub trait DatabaseClientMethods {
+    /// Reads the properties of the database.
+    ///
+    /// # Arguments
+    ///
+    /// * `options` - Optional parameters for the request.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// # async fn doc() {
+    /// use azure_data_cosmos::{CosmosClient, CosmosClientMethods, DatabaseClientMethods};
+    ///
+    /// let credential = azure_identity::create_default_credential().unwrap();
+    /// let client = CosmosClient::new("https://myaccount.documents.azure.com/", credential, None).unwrap();
+    /// let db_client = client.database("my_database");
+    /// let response = db_client.read(None)
+    ///     .await.unwrap()
+    ///     .deserialize_body()
+    ///     .await.unwrap();
+    /// # }
+    /// ```
     fn read(
         &self,
         options: Option<ReadDatabaseOptions>,
     ) -> impl std::future::Future<Output = azure_core::Result<azure_core::Response<DatabaseProperties>>>;
 }
 
+/// A client for working with a specific database in a Cosmos account.
+///
+/// You can get a `DatabaseClient` by calling [`CosmosClient::database()`](CosmosClient::database).
 pub struct DatabaseClient {
     base_url: Url,
     root_client: CosmosClient,
@@ -40,7 +71,10 @@ impl DatabaseClient {
 impl DatabaseClientMethods for DatabaseClient {
     async fn read(
         &self,
-        _options: Option<ReadDatabaseOptions>,
+
+        #[allow(unused_variables)]
+        // This is a documented public API so prefixing with '_' is undesirable.
+        options: Option<ReadDatabaseOptions>,
     ) -> azure_core::Result<azure_core::Response<DatabaseProperties>> {
         let mut req = Request::new(self.base_url.clone(), azure_core::Method::Get);
         let ctx = Context::new().with_value(ResourceType::Databases);

sdk/cosmosdb/azure_data_cosmos/src/lib.rs

@@ -1,7 +1,18 @@
+#![doc = include_str!("../README.md")]
+// Docs.rs build is done with the nightly compiler, so we can enable nightly features in that build.
+// In this case we enable two features:
+// - `doc_auto_cfg`: Automatically scans `cfg` attributes and uses them to show those required configurations in the generated documentation.
+// - `doc_cfg_hide`: Ignore the `doc` configuration for `doc_auto_cfg`.
+// See https://doc.rust-lang.org/rustdoc/unstable-features.html#doc_auto_cfg-automatically-generate-doccfg for more details.
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg_hide))]
+
 mod authorization_policy;
 mod clients;
-pub mod models;
 mod options;
 
+/// Model types sent to and received from the Cosmos API.
+pub mod models;
+
 pub use clients::*;
 pub use options::*;

sdk/cosmosdb/azure_data_cosmos/src/models/mod.rs

@@ -2,34 +2,50 @@ use serde::{Deserialize, Serialize};
 use time::error::ComponentRange;
 use time::OffsetDateTime;
 
-#[derive(Debug, Serialize, Deserialize)]
-pub struct SystemProperties {
-    #[serde(rename = "_etag")]
-    pub etag: Option<azure_core::Etag>,
-    #[serde(rename = "_self")]
-    pub self_link: Option<String>,
-    #[serde(rename = "_rid")]
-    pub resource_id: Option<String>,
-    #[serde(rename = "_ts")]
-    pub last_modified: Option<CosmosTimestamp>,
-}
+#[cfg(doc)]
+use crate::DatabaseClientMethods;
 
+/// Represents a timestamp in the format expected by Cosmos DB.
+///
+/// Cosmos DB timestamps are represented as the number of seconds since the Unix epoch.
+/// Use [`CosmosTimestamp::try_into`] implementation to convert this into a [`time::OffsetDateTime`].
 #[derive(Serialize, Deserialize, Debug)]
 pub struct CosmosTimestamp(i64);
 
+/// Converts a [`CosmosTimestamp`] into a [`OffsetDateTime`].
 impl TryInto<OffsetDateTime> for CosmosTimestamp {
     type Error = ComponentRange;
 
+    /// Attempts to convert this [`CosmosTimestamp`] into a [`OffsetDateTime`].
     fn try_into(self) -> Result<OffsetDateTime, Self::Error> {
         OffsetDateTime::from_unix_timestamp(self.0)
     }
 }
 
+/// Properties of a Cosmos DB database.
+///
+/// Returned by [`DatabaseClient::read()`](crate::DatabaseClient::read()).
 #[derive(Debug, Deserialize)]
 pub struct DatabaseProperties {
+    /// The ID of the database.
     pub id: String,
 
-    #[serde(flatten)]
-    pub system_properties: SystemProperties,
+    /// The entity tag associated with the resource.
+    #[serde(rename = "_etag")]
+    pub etag: Option<azure_core::Etag>,
+
+    /// The self-link associated with the resource.
+    #[serde(rename = "_self")]
+    pub self_link: Option<String>,
+
+    /// The system-generated unique identifier associated with the resource.
+    #[serde(rename = "_rid")]
+    pub resource_id: Option<String>,
+
+    /// A [`CosmosTimestamp`] representing the last modified time of the resource.
+    #[serde(rename = "_ts")]
+    pub last_modified: Option<CosmosTimestamp>,
 }
+
+// TODO: Migrate to derive macro once https://github.com/Azure/azure-sdk-for-rust/pull/1772 lands.
 azure_core::json_model!(DatabaseProperties);

sdk/cosmosdb/azure_data_cosmos/src/options/mod.rs

@@ -1,37 +1,72 @@
 use azure_core::ClientOptions;
 
+/// Options used when creating a [`CosmosClient`](crate::CosmosClient).
+///
+/// NOTE: There are currently no options to set on this type.
+/// It exists to enable future extensibility.
 #[derive(Clone, Debug, Default)]
 pub struct CosmosClientOptions {
     pub(crate) client_options: ClientOptions,
 }
 
 impl CosmosClientOptions {
+    /// Creates a new [`CosmosClientOptionsBuilder`](builders::CosmosClientOptionsBuilder) that can be used to construct a [`CosmosClientOptions`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// let options = azure_data_cosmos::ReadDatabaseOptions::builder().build();
+    /// ```
     pub fn builder() -> builders::CosmosClientOptionsBuilder {
         builders::CosmosClientOptionsBuilder::default()
     }
 }
 
+/// Options to be passed to [`DatabaseClientMethods::read()`](crate::DatabaseClientMethods::read()).
+///
+/// NOTE: There are currently no options to set on this type.
+/// It exists to enable future extensibility.
 #[derive(Clone, Debug, Default)]
 pub struct ReadDatabaseOptions {}
 
-impl ReadDatabaseOptions {}
+impl ReadDatabaseOptions {
+    /// Creates a new [`ReadDatabaseOptionsBuilder`](builders::ReadDatabaseOptionsBuilder) that can be used to construct a [`ReadDatabaseOptions`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// let options = azure_data_cosmos::ReadDatabaseOptions::builder().build();
+    /// ```
+    pub fn builder() -> builders::ReadDatabaseOptionsBuilder {
+        builders::ReadDatabaseOptionsBuilder::default()
+    }
+}
 
+/// Builders for Cosmos-related options structs.
 pub mod builders {
     use crate::{CosmosClientOptions, ReadDatabaseOptions};
 
+    /// Builder used to construct a [`CosmosClientOptions`].
     #[derive(Default)]
     pub struct CosmosClientOptionsBuilder(CosmosClientOptions);
 
     impl CosmosClientOptionsBuilder {
+        /// Builds a [`CosmosClientOptions`] object from the builder.
+        ///
+        /// This does not consume the builder, and can be called multiple times.
         pub fn build(&self) -> CosmosClientOptions {
             self.0.clone()
         }
     }
 
+    /// Builder used to construct a [`ReadDatabaseOptions`].
     #[derive(Default)]
     pub struct ReadDatabaseOptionsBuilder(ReadDatabaseOptions);
 
     impl ReadDatabaseOptionsBuilder {
+        /// Builds a [`CosmosClientOptions`] object from the builder.
+        ///
+        /// This does not consume the builder, and can be called multiple times.
         pub fn build(&self) -> ReadDatabaseOptions {
             self.0.clone()
         }