Enabled doc comments in azure_core and azure_identity packages (#2990)

Also:

Removed a significant number of unused HTTP headers from azure_core.

Author: LarryOsterman

sdk/core/azure_core/CHANGELOG.md

@@ -6,6 +6,8 @@
 
 ### Breaking Changes
 
+- Removed several unreferenced HTTP headers and accessor structures for those headers.
+
 ### Bugs Fixed
 
 ### Other Changes

sdk/core/azure_core/src/credentials.rs

@@ -17,13 +17,15 @@ pub static DEFAULT_SCOPE_SUFFIX: &str = "/.default";
 pub struct Secret(Cow<'static, str>);
 
 impl Secret {
+    /// Create a new `Secret`.
     pub fn new<T>(access_token: T) -> Self
     where
         T: Into<Cow<'static, str>>,
     {
         Self(access_token.into())
     }
 
+    /// Get the secret value.
     pub fn secret(&self) -> &str {
         &self.0
     }
@@ -90,6 +92,7 @@ impl AccessToken {
 /// Options for getting a token from a [`TokenCredential`]
 #[derive(Clone, Default, SafeDebug)]
 pub struct TokenRequestOptions<'a> {
+    /// Method options to be used when requesting a token.
     pub method_options: ClientMethodOptions<'a>,
 }
 

sdk/core/azure_core/src/error/mod.rs

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+//! Error types and handling.
 pub use typespec_client_core::error::*;
 mod error_response;
 

sdk/core/azure_core/src/http/headers.rs

@@ -9,48 +9,19 @@ pub use typespec_client_core::http::headers::*;
 // HTTP headers are case-insensitive.
 // We use lowercase below for simple comparisons downstream.
 
-pub const ACCOUNT_KIND: HeaderName = HeaderName::from_static("x-ms-account-kind");
-pub(crate) const ACTIVITY_ID: HeaderName = HeaderName::from_static("x-ms-activity-id");
-pub(crate) const APP: HeaderName = HeaderName::from_static("x-ms-app");
-pub const APPEND_POSITION: HeaderName = HeaderName::from_static("x-ms-blob-condition-appendpos"); // cspell:ignore appendpos
-pub const AZURE_ASYNCOPERATION: HeaderName = HeaderName::from_static("azure-asyncoperation");
-pub(crate) const BLOB_SEQUENCE_NUMBER: HeaderName =
-    HeaderName::from_static("x-ms-blob-sequence-number");
+/// x-ms-client-request-id header. See <https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#distributed-tracing--telemetry> for more details.
 pub const CLIENT_REQUEST_ID: HeaderName = HeaderName::from_static("x-ms-client-request-id");
-pub(crate) const CLIENT_VERSION: HeaderName = HeaderName::from_static("x-ms-client-version");
-pub(crate) const CONTENT_DISPOSITION: HeaderName =
-    HeaderName::from_static("x-ms-blob-content-disposition");
-pub(crate) const CONTINUATION: HeaderName = HeaderName::from_static("x-ms-continuation");
+/// x-ms-error-code header. See <https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors> for more details.
 pub const ERROR_CODE: HeaderName = HeaderName::from_static("x-ms-error-code");
-pub(crate) const IF_SEQUENCE_NUMBER_EQ: HeaderName =
-    HeaderName::from_static("x-ms-if-sequence-number-eq");
-pub(crate) const IF_SEQUENCE_NUMBER_LE: HeaderName =
-    HeaderName::from_static("x-ms-if-sequence-number-le");
-pub(crate) const IF_SEQUENCE_NUMBER_LT: HeaderName =
-    HeaderName::from_static("x-ms-if-sequence-number-lt");
-pub(crate) const IF_TAGS: HeaderName = HeaderName::from_static("x-ms-if-tags");
-pub(crate) const LEASE_BREAK_PERIOD: HeaderName =
-    HeaderName::from_static("x-ms-lease-break-period");
-pub(crate) const LEASE_DURATION: HeaderName = HeaderName::from_static("x-ms-lease-duration");
-pub(crate) const LEASE_ID: HeaderName = HeaderName::from_static("x-ms-lease-id");
-pub(crate) const MAX_ITEM_COUNT: HeaderName = HeaderName::from_static("x-ms-max-item-count");
+/// x-ms-date header.
 pub const MS_DATE: HeaderName = HeaderName::from_static("x-ms-date");
-pub(crate) const MS_RANGE: HeaderName = HeaderName::from_static("x-ms-range");
-pub(crate) const PROPOSED_LEASE_ID: HeaderName = HeaderName::from_static("x-ms-proposed-lease-id");
-pub(crate) const RANGE_GET_CONTENT_CRC64: HeaderName =
-    HeaderName::from_static("x-ms-range-get-content-crc64");
+/// x-ms-request-id header. See <https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#distributed-tracing--telemetry> for more details.
 pub(crate) const REQUEST_ID: HeaderName = HeaderName::from_static("x-ms-request-id");
+/// retry-after-ms header.
 pub const RETRY_AFTER_MS: HeaderName = HeaderName::from_static("retry-after-ms");
-pub(crate) const SOURCE_IF_MATCH: HeaderName = HeaderName::from_static("x-ms-source-if-match");
-pub(crate) const SOURCE_IF_MODIFIED_SINCE: HeaderName =
-    HeaderName::from_static("x-ms-source-if-modified-since");
-pub(crate) const SOURCE_IF_NONE_MATCH: HeaderName =
-    HeaderName::from_static("x-ms-source-if-none-match");
-pub(crate) const SOURCE_IF_UNMODIFIED_SINCE: HeaderName =
-    HeaderName::from_static("x-ms-source-if-unmodified-since");
-pub(crate) const SOURCE_LEASE_ID: HeaderName = HeaderName::from_static("x-ms-source-lease-id");
-pub(crate) const USER: HeaderName = HeaderName::from_static("x-ms-user");
+/// x-ms-version header.
 pub const VERSION: HeaderName = HeaderName::from_static("x-ms-version");
+/// x-ms-retry-after-ms header.
 pub const X_MS_RETRY_AFTER_MS: HeaderName = HeaderName::from_static("x-ms-retry-after-ms");
 
 /// Constants related to the Content-Type header
@@ -62,11 +33,7 @@ pub mod content_type {
     // Form content types
     // https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4
 
+    /// The content type for form payloads. See <https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4> for more details.
     pub const APPLICATION_X_WWW_FORM_URLENCODED: HeaderValue =
         HeaderValue::from_static("application/x-www-form-urlencoded");
 }
-
-/// Constants related to query parameters
-pub mod query_param {
-    pub const API_VERSION: &str = "api-version";
-}

sdk/core/azure_core/src/http/models/lease.rs

@@ -1,7 +1,4 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-mod lease;
-
-pub use lease::*;
 pub use typespec_client_core::http::Etag;

sdk/core/azure_core/src/http/models/mod.rs

@@ -76,9 +76,17 @@ impl<C: Clone + AsRef<str>> Clone for PagerState<C> {
 /// The result of fetching a single page from a [`Pager`], whether there are more pages or paging is done.
 pub enum PagerResult<P, C: AsRef<str>> {
     /// There are more pages the [`Pager`] may fetch using the `continuation` token.
-    More { response: P, continuation: C },
+    More {
+        /// The response for the current page.
+        response: P,
+        /// The continuation token for the next page.
+        continuation: C,
+    },
     /// The [`Pager`] is done and there are no additional pages to fetch.
-    Done { response: P },
+    Done {
+        /// The response for the current page.
+        response: P,
+    },
 }
 
 impl<P, F> PagerResult<Response<P, F>, String> {

sdk/core/azure_core/src/http/pager.rs

@@ -24,6 +24,7 @@ pub struct BearerTokenCredentialPolicy {
 }
 
 impl BearerTokenCredentialPolicy {
+    /// Creates a new `BearerTokenCredentialPolicy`.
     pub fn new<A, B>(credential: Arc<dyn TokenCredential>, scopes: A) -> Self
     where
         A: IntoIterator<Item = B>,

sdk/core/azure_core/src/http/policies/bearer_token_policy.rs

@@ -171,8 +171,11 @@ pub enum PollerResult<M, N> {
     /// * `retry_after` is the optional client-specified [`Duration`] to wait. The default is 30 seconds.
     /// * `next` is the next link / continuation token.
     InProgress {
+        /// The HTTP response with the status monitor.
         response: Response<M>,
+        /// The optional client-specified [`Duration`] to wait before polling again.
         retry_after: Option<Duration>,
+        /// The next link / continuation token.
         next: N,
     },
 
@@ -181,7 +184,10 @@ pub enum PollerResult<M, N> {
     /// # Fields
     ///
     /// * `response` contains the HTTP response with the status monitor in a terminal state.
-    Done { response: Response<M> },
+    Done {
+        /// The HTTP response with the status monitor in a terminal state.
+        response: Response<M>,
+    },
 }
 
 impl<M: StatusMonitor, N: fmt::Debug> fmt::Debug for PollerResult<M, N> {