From 4c5cbc39384f0d949d7693eb87b5853fe72629cd Mon Sep 17 00:00:00 2001 From: Luca Palmieri Date: Fri, 30 Sep 2022 12:30:47 +0100 Subject: [PATCH] Fix a few rendering issues in the design docs (#1787) * Fix backtick fences to render code block * Render list as a list instead of a code block. * Indent further to get nested code block. * Remove `ignore` descriptors. --- design/src/smithy/aggregate_shapes.md | 24 ++++++++++++------------ design/src/smithy/recursive_shapes.md | 2 +- design/src/transport/operation.md | 4 ++-- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/design/src/smithy/aggregate_shapes.md b/design/src/smithy/aggregate_shapes.md index e411277bf..0f63a2e5e 100644 --- a/design/src/smithy/aggregate_shapes.md +++ b/design/src/smithy/aggregate_shapes.md @@ -28,10 +28,10 @@ Smithy `structure` becomes a `struct` in Rust. Backwards compatibility & usabili 2. All structs are marked `#[non_exhaustive]` 3. All structs derive `Debug` & `PartialEq`. Structs **do not** derive `Eq` because a `float` member may be added in the future. 4. Struct fields are public. Public struct fields allow for [split borrows](https://doc.rust-lang.org/nomicon/borrow-splitting.html). When working with output objects this significantly improves ergonomics, especially with optional fields. - ```rust,ignore - let out = dynamo::ListTablesOutput::new(); - out.some_field.unwrap(); // <- partial move, impossible with an accessor - ``` + ```rust + let out = dynamo::ListTablesOutput::new(); + out.some_field.unwrap(); // <- partial move, impossible with an accessor + ``` 5. Builders are generated for structs that provide ergonomic and backwards compatible constructors. A builder for a struct is always available via the convenience method `SomeStruct::builder()` 6. Structures manually implement debug: In order to support the [sensitive trait](https://awslabs.github.io/smithy/1.0/spec/core/documentation-traits.html#sensitive-trait), a `Debug` implementation for structures is manually generated. @@ -52,7 +52,7 @@ long ReadIOs long WriteIOs ``` **Rust Output**: -```rust,ignore +```rust ///

Contains I/O usage metrics for a command that was invoked.

#[non_exhaustive] #[derive(std::clone::Clone, std::cmp::PartialEq)] @@ -118,12 +118,12 @@ impl IOUsage { ## Union Smithy `Union` is modeled as `enum` in Rust. - 1. Generated `enum`s must be marked `#[non_exhaustive]`. - 2. Generated `enum`s must provide an `Unknown` variant. If parsing receives an unknown input that doesn't match any of the given union variants, `Unknown` should be constructed. [Tracking Issue](https://github.com/awslabs/smithy-rs/issues/185). - 1. Union members (enum variants) are **not** nullable, because Smithy union members cannot contain null values. - 2. When union members contain references to other shapes, we generate a wrapping variant (see below). - 3. Union members do not require `#[non_exhaustive]`, because changing the shape targeted by a union member is not backwards compatible. - 4. `is_variant` and `as_variant` helper functions are generated to improve ergonomics. +1. Generated `enum`s must be marked `#[non_exhaustive]`. +2. Generated `enum`s must provide an `Unknown` variant. If parsing receives an unknown input that doesn't match any of the given union variants, `Unknown` should be constructed. [Tracking Issue](https://github.com/awslabs/smithy-rs/issues/185). +3. Union members (enum variants) are **not** nullable, because Smithy union members cannot contain null values. +4. When union members contain references to other shapes, we generate a wrapping variant (see below). +5. Union members do not require `#[non_exhaustive]`, because changing the shape targeted by a union member is not backwards compatible. +6. `is_variant` and `as_variant` helper functions are generated to improve ergonomics. ### Generated Union Example The union generated for a simplified `dynamodb::AttributeValue` @@ -149,7 +149,7 @@ list BoolList { } ``` **Rust**: -```rust,ignore +```rust #[non_exhaustive] #[derive(std::clone::Clone, std::cmp::PartialEq, std::fmt::Debug)] pub enum AttributeValue { diff --git a/design/src/smithy/recursive_shapes.md b/design/src/smithy/recursive_shapes.md index 61f4ec7b5..1697fb0dd 100644 --- a/design/src/smithy/recursive_shapes.md +++ b/design/src/smithy/recursive_shapes.md @@ -13,7 +13,7 @@ struct IntermediateStructure { } ``` -```rust,ignore +```text | 3 | struct TopStructure { | ^^^^^^^^^^^^^^^^^^^ recursive type has infinite size diff --git a/design/src/transport/operation.md b/design/src/transport/operation.md index 9ca8a4dfc..332e60765 100644 --- a/design/src/transport/operation.md +++ b/design/src/transport/operation.md @@ -16,7 +16,7 @@ This section details the flow of a request through the SDK until a response is r A customer interacts with the SDK builders to construct an input. The `build()` method on an input returns an `Operation`. This codifies the base HTTP request & all the configuration and middleware layers required to modify and dispatch the request. -```rust,ignore +```rust pub struct Operation { request: Request, response_handler: H, @@ -37,7 +37,7 @@ By using a property bag, we can define the `Operation` in Smithy core. AWS speci In order to construct an operation, the generated code injects appropriate middleware & configuration via the configuration property bag. It does this by reading the configuration properties out of the service config, copying them as necessary, and loading them into the `Request`: -```rust,ignore +```rust // This is approximately the generated code, I've cleaned a few things up for readability. pub fn build(self, config: &dynamodb::config::Config) -> Operation { let op = BatchExecuteStatement::new(BatchExecuteStatementInput { -- GitLab