Require doccoments in typespec and typespec_client_core packages (#2972)

Partial fix for #1709

---------

Co-authored-by: Copilot <[email protected]>

Author: LarryOsterman

sdk/core/azure_core_macros/src/lib.rs

@@ -2,6 +2,8 @@
 // Licensed under the MIT License.
 
 #![doc = include_str!("../README.md")]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![warn(missing_docs)]
 
 mod tracing;
 mod tracing_client;
@@ -41,6 +43,13 @@ pub fn new(attr: TokenStream, item: TokenStream) -> TokenStream {
         .map_or_else(|e| e.into_compile_error().into(), |v| v.into())
 }
 
+/// Attribute client subclient struct declarations to enable distributed tracing.
+///
+/// To declare a subclient that will be traced, you should use the `#[tracing::subclient]` attribute
+/// exported from azure_core.
+///
+/// This macro will automatically instrument the subclient declaration with tracing information. It will also ensure that the subclient is created with the necessary tracing context.
+/// The `#[tracing::subclient]` attribute takes a single argument, which is a string representing the Azure Namespace name for the service being traced.
 #[proc_macro_attribute]
 pub fn subclient(attr: TokenStream, item: TokenStream) -> TokenStream {
     tracing_subclient::parse_subclient(attr.into(), item.into())
@@ -49,6 +58,15 @@ pub fn subclient(attr: TokenStream, item: TokenStream) -> TokenStream {
 
 /// Attribute client public APIs to enable distributed tracing.
 ///
+/// To declare a public API function that will be traced, you should use the `#[tracing::function]` attribute
+/// exported from azure_core.
+///
+/// This macro will automatically instrument the public API function with tracing information. It will also ensure that the function is executed with the necessary tracing context.
+///
+/// The `function` attribute takes one required argument, which is a string representing the name of the operation being traced.
+/// This name will be used in the tracing spans to identify the operation being performed. The name should be unique and match the
+/// typespec name for the operation being traced if possible.
+///
 #[proc_macro_attribute]
 pub fn function(attr: TokenStream, item: TokenStream) -> TokenStream {
     tracing_function::parse_function(attr.into(), item.into())

sdk/template/azure_template_core/README.md

@@ -1 +1 @@
-Template crate for Azure SDK pipeline testing
+# Template crate for Azure SDK pipeline testing

sdk/template/azure_template_core/src/lib.rs

@@ -1,6 +1,10 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+#![doc = include_str!("../README.md")]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![warn(missing_docs)]
+
 /// Core numeric traits and types
 pub mod numeric {
     /// Core trait for numeric operations
@@ -18,6 +22,14 @@ pub mod numeric {
 
 pub use numeric::NumericCore;
 
+/// Adds two `u64` values and returns the result.
+///
+/// # Examples
+/// ```
+/// # use azure_template_core::add;
+/// let sum = add(5, 10);
+/// assert_eq!(sum, 15);
+/// ```
 pub fn add(left: u64, right: u64) -> u64 {
     left + right
 }

sdk/typespec/src/error/mod.rs

@@ -22,7 +22,9 @@ pub enum ErrorKind {
     /// An HTTP status code that was not expected.
     #[cfg(feature = "http")]
     HttpResponse {
+        /// The HTTP status code that was returned.
         status: StatusCode,
+        /// An optional error code returned by the service.
         error_code: Option<String>,
     },
     /// An error performing IO.
@@ -170,6 +172,7 @@ impl Error {
         }
     }
 
+    /// If this error is an HTTP response error, return the associated status code.
     #[cfg(feature = "http")]
     pub fn http_status(&self) -> Option<StatusCode> {
         match &self.kind() {

sdk/typespec/src/http/mod.rs

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+//! This module contains types and utilities for working with HTTP status codes.
+
 mod status_code;
 
 pub use status_code::StatusCode;

sdk/typespec/src/lib.rs

@@ -3,6 +3,7 @@
 
 #![doc = include_str!("../README.md")]
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![warn(missing_docs)]
 
 pub mod error;
 #[cfg(feature = "http")]

sdk/typespec/typespec_client_core/src/async_runtime/mod.rs

@@ -42,10 +42,11 @@ mod web_runtime;
 #[cfg(test)]
 mod tests;
 
+/// A `TaskFuture` is a boxed future that represents a task that can be spawned and executed asynchronously.
 #[cfg(not(target_arch = "wasm32"))]
 pub type TaskFuture = Pin<Box<dyn Future<Output = ()> + Send + 'static>>;
 
-// WASM32 does not support `Send` futures, so we use a non-Send future type.
+/// A `TaskFuture` is a boxed future that represents a task that can be spawned and executed asynchronously.
 #[cfg(target_arch = "wasm32")]
 pub type TaskFuture = Pin<Box<dyn Future<Output = ()> + 'static>>;
 
@@ -60,6 +61,8 @@ pub type SpawnedTask = Pin<
     >,
 >;
 
+/// A `SpawnedTask` is a future that represents a running task.
+/// It can be awaited to block until the task has completed.
 #[cfg(target_arch = "wasm32")]
 pub type SpawnedTask =
     Pin<Box<dyn Future<Output = std::result::Result<(), Box<dyn std::error::Error>>> + 'static>>;
@@ -105,6 +108,12 @@ pub trait AsyncRuntime: Send + Sync {
     /// that can be awaited.
     fn spawn(&self, f: TaskFuture) -> SpawnedTask;
 
+    /// Sleep for the specified duration asynchronously.
+    ///
+    /// # Arguments
+    /// * `duration` - The duration to sleep for.
+    /// # Returns
+    /// A future that resolves after the specified duration has elapsed.
     fn sleep(&self, duration: Duration) -> TaskFuture;
 }
 

sdk/typespec/typespec_client_core/src/base64.rs

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+// cspell:ignore Hdvcmxk
+
 //! Base64 encoding and decoding functions.
 
 use base64::{
@@ -25,27 +27,87 @@ const URL_SAFE: GeneralPurpose = GeneralPurpose::new(
         .with_encode_padding(false),
 );
 
+/// Encode the input into a base64 string using the standard base64 encoding scheme.
+///
+/// # Arguments
+/// * `input` - The input data to encode, which can be any type that implements `AsRef<[u8]>`.
+///
+/// # Returns
+/// A `String` containing the base64 encoded representation of the input data.
+///
+/// # Examples
+/// ```rust
+/// # use typespec_client_core::base64;
+/// let data = b"Hello, world!";
+/// let encoded = base64::encode(data);
+/// assert_eq!(encoded, "SGVsbG8sIHdvcmxkIQ==");
+/// ```
 pub fn encode<T>(input: T) -> String
 where
     T: AsRef<[u8]>,
 {
     STANDARD.encode(input)
 }
 
+/// Decode a base64 encoded string using the standard base64 decoding scheme.
+///
+/// # Arguments
+/// * `input` - The base64 encoded input data to decode, which can be any type that implements `AsRef<[u8]>`.
+///
+/// # Returns
+/// A `Result` containing a `Vec<u8>` with the decoded data, or an error if the input is not valid base64.
+///
+/// # Examples
+/// ```rust
+/// # use typespec_client_core::base64;
+/// let encoded = "SGVsbG8sIHdvcmxkIQ==";
+/// let decoded = base64::decode(encoded).expect("Decoding should succeed");
+/// assert_eq!(decoded, b"Hello, world!");
+/// ```
 pub fn decode<T>(input: T) -> crate::Result<Vec<u8>>
 where
     T: AsRef<[u8]>,
 {
     Ok(STANDARD.decode(input)?)
 }
 
+/// Encode the input into a base64 string using the URL safe base64 encoding scheme (base64url).
+///
+/// # Arguments
+/// * `input` - The input data to encode, which can be any type that implements `AsRef<[u8]>`.
+///
+/// # Returns
+/// A `String` containing the base64url encoded representation of the input data.
+///
+/// # Examples
+/// ```rust
+/// # use typespec_client_core::base64;
+/// let data = b"Hello, world!";
+/// let encoded = base64::encode_url_safe(data);
+/// assert_eq!(encoded, "SGVsbG8sIHdvcmxkIQ");
+/// ```
 pub fn encode_url_safe<T>(input: T) -> String
 where
     T: AsRef<[u8]>,
 {
     URL_SAFE.encode(input)
 }
 
+/// Decode a base64url encoded string using the URL safe base64 decoding scheme. (base64url)
+///
+/// # Arguments
+/// * `input` - The base64url encoded input data to decode, which can be any type that implements `AsRef<[u8]>`.
+///
+/// # Returns
+/// A `Result` containing a `Vec<u8>` with the decoded data, or an error if the input is not valid base64url.
+///
+/// # Examples
+/// ```rust
+/// # use typespec_client_core::base64;
+/// let encoded = "SGVsbG8sIHdvcmxkIQ";
+/// let decoded = base64::decode_url_safe(encoded).expect("Decoding should succeed");
+/// assert_eq!(decoded, b"Hello, world!");
+/// ```
 pub fn decode_url_safe<T>(input: T) -> crate::Result<Vec<u8>>
 where
     T: AsRef<[u8]>,

sdk/typespec/typespec_client_core/src/http/format.rs

@@ -25,6 +25,13 @@ pub trait Format: std::fmt::Debug {}
 #[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))]
 #[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)]
 pub trait DeserializeWith<F: Format>: Sized {
+    /// Deserialize the response body using the specified format.
+    ///
+    /// # Arguments
+    /// * `body` - The response body to deserialize.
+    ///
+    /// # Returns
+    /// A `Result` containing the deserialized value of type `Self`, or an error if deserialization fails.
     async fn deserialize_with(body: ResponseBody) -> typespec::Result<Self>;
 }
 

sdk/typespec/typespec_client_core/src/http/headers/common.rs

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+#![allow(missing_docs)]
+
 use super::*;
 
 // HTTP headers are case-insensitive.