From faeced02b0ef430546212b7d41911cbedb72b07b Mon Sep 17 00:00:00 2001 From: Rick Winter Date: Wed, 16 Apr 2025 11:20:18 -0700 Subject: [PATCH 1/4] Add a readme for the macros crate Calls out that the crate should not be used directly --- sdk/typespec/typespec_macros/README.md | 81 ++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 sdk/typespec/typespec_macros/README.md diff --git a/sdk/typespec/typespec_macros/README.md b/sdk/typespec/typespec_macros/README.md new file mode 100644 index 0000000000..aca6f16799 --- /dev/null +++ b/sdk/typespec/typespec_macros/README.md @@ -0,0 +1,81 @@ +# TypeSpec Macros crate for Rust + +The TypeSpec Macros crate provides procedural macros for [TypeSpec](https://typespec.io)-generated client libraries. These macros simplify the implementation of common patterns required when working with TypeSpec-generated code. + +[Source code] | [Package (crates.io)] | [API reference documentation] | [TypeSpec documentation] + +## Getting started + +> **Note:** This crate should not be used directly. Users should depend on the `typespec_client_core` crate instead. +### Install the package + +If you need to use this crate directly, install the TypeSpec Macros crate for Rust with cargo: + +```bash +cargo add typespec_macros +``` + +## Key concepts + +This crate provides the following derive macros: + +- `Model`: A derive macro that implements the `Model` trait, allowing a type to be deserialized from an HTTP response body. +- `SafeDebug`: A derive macro that implements debug formatting in a way that avoids leaking personally identifiable information (PII). + +### The Model derive macro + +The `Model` derive macro is used to implement the `Model` trait for structs that represent data returned from an API. It handles the deserialization of HTTP response bodies into your model types. + +### The SafeDebug derive macro + +The `SafeDebug` derive macro creates a `Debug` implementation that respects the `#[sensitive]` attribute on struct fields. Fields marked with this attribute will not have their values printed in debug output, protecting potentially sensitive information. + +## Examples + +### Using the Model derive macro + +```rust +use typespec_macros::Model; +use serde::Deserialize; + +#[derive(Model, Deserialize)] +pub struct User { + pub id: String, + pub name: String, + pub email: String, +} +``` + +### Using the SafeDebug derive macro + +```rust +use typespec_macros::SafeDebug; + +#[derive(SafeDebug)] +pub struct Credentials { + pub username: String, + #[sensitive] + pub password: String, +} + +// When debug printed, the password will be hidden: +// Credentials { username: "user123", password: "***" } +``` + +## Contributing + +See the [CONTRIBUTING.md] for details on building, testing, and contributing to this library. + +This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit . + +When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. + +This project has adopted the [Microsoft Open Source Code of Conduct]. For more information see the [Code of Conduct FAQ] or contact with any additional questions or comments. + +[Source code]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/typespec/typespec_macros/src +[Package (crates.io)]: https://crates.io/crates/typespec_macros +[API reference documentation]: https://docs.rs/typespec_macros +[TypeSpec documentation]: https://typespec.io/ +[CONTRIBUTING.md]: https://github.com/Azure/azure-sdk-for-rust/blob/main/CONTRIBUTING.md +[Microsoft Open Source Code of Conduct]: https://opensource.microsoft.com/codeofconduct/ +[Code of Conduct FAQ]: https://opensource.microsoft.com/codeofconduct/faq/ From 438ddbb7e1f7f4234f8d208f79b404532934e7f0 Mon Sep 17 00:00:00 2001 From: Rick Winter Date: Wed, 16 Apr 2025 11:22:08 -0700 Subject: [PATCH 2/4] Update sdk/typespec/typespec_macros/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- sdk/typespec/typespec_macros/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/typespec/typespec_macros/README.md b/sdk/typespec/typespec_macros/README.md index aca6f16799..3f230158c5 100644 --- a/sdk/typespec/typespec_macros/README.md +++ b/sdk/typespec/typespec_macros/README.md @@ -6,10 +6,10 @@ The TypeSpec Macros crate provides procedural macros for [TypeSpec](https://type ## Getting started -> **Note:** This crate should not be used directly. Users should depend on the `typespec_client_core` crate instead. +> **Note:** This crate is primarily intended for internal use by the `typespec_client_core` crate. Direct usage is discouraged unless you are contributing to or debugging the TypeSpec ecosystem. ### Install the package -If you need to use this crate directly, install the TypeSpec Macros crate for Rust with cargo: +> **Disclaimer:** The following instructions are intended for advanced users or contributors who need to work directly with the `typespec_macros` crate. Most users should depend on the `typespec_client_core` crate instead. ```bash cargo add typespec_macros From c2ae249b691e79528537bb0b97bd3b61998cbd99 Mon Sep 17 00:00:00 2001 From: Rick Winter Date: Wed, 16 Apr 2025 12:54:08 -0700 Subject: [PATCH 3/4] Cleanup the readme from feedback --- sdk/typespec/typespec_macros/README.md | 41 +------------------------- 1 file changed, 1 insertion(+), 40 deletions(-) diff --git a/sdk/typespec/typespec_macros/README.md b/sdk/typespec/typespec_macros/README.md index aca6f16799..a815c0bedf 100644 --- a/sdk/typespec/typespec_macros/README.md +++ b/sdk/typespec/typespec_macros/README.md @@ -6,14 +6,7 @@ The TypeSpec Macros crate provides procedural macros for [TypeSpec](https://type ## Getting started -> **Note:** This crate should not be used directly. Users should depend on the `typespec_client_core` crate instead. -### Install the package - -If you need to use this crate directly, install the TypeSpec Macros crate for Rust with cargo: - -```bash -cargo add typespec_macros -``` +> **Note:** This crate supports `typespec_client_core` e.g., deriving the `Model` trait, and should not be imported directly. Import `typespec_client_core` instead. Read its [documentation](https://docs.rs/typespec_client_core) for more information. ## Key concepts @@ -30,38 +23,6 @@ The `Model` derive macro is used to implement the `Model` trait for structs that The `SafeDebug` derive macro creates a `Debug` implementation that respects the `#[sensitive]` attribute on struct fields. Fields marked with this attribute will not have their values printed in debug output, protecting potentially sensitive information. -## Examples - -### Using the Model derive macro - -```rust -use typespec_macros::Model; -use serde::Deserialize; - -#[derive(Model, Deserialize)] -pub struct User { - pub id: String, - pub name: String, - pub email: String, -} -``` - -### Using the SafeDebug derive macro - -```rust -use typespec_macros::SafeDebug; - -#[derive(SafeDebug)] -pub struct Credentials { - pub username: String, - #[sensitive] - pub password: String, -} - -// When debug printed, the password will be hidden: -// Credentials { username: "user123", password: "***" } -``` - ## Contributing See the [CONTRIBUTING.md] for details on building, testing, and contributing to this library. From 574d7e4ccd64b5499efa07f27b14e47f64919df2 Mon Sep 17 00:00:00 2001 From: Rick Winter Date: Wed, 16 Apr 2025 13:11:41 -0700 Subject: [PATCH 4/4] Remove empty section --- sdk/typespec/typespec_macros/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/sdk/typespec/typespec_macros/README.md b/sdk/typespec/typespec_macros/README.md index 85a26ea429..d0eae7a27b 100644 --- a/sdk/typespec/typespec_macros/README.md +++ b/sdk/typespec/typespec_macros/README.md @@ -8,8 +8,6 @@ The TypeSpec Macros crate provides procedural macros for [TypeSpec](https://type > **Note:** This crate is primarily intended for internal use by the `typespec_client_core` crate. Direct usage is discouraged unless you are contributing to or debugging the TypeSpec ecosystem. -### Install the package - ## Key concepts This crate provides the following derive macros: