Unverified Commit 4c5cbc39 authored by Luca Palmieri's avatar Luca Palmieri Committed by GitHub
Browse files

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.
parent 4cfac14d

design/src/smithy/aggregate_shapes.md

+12 −12
Original line number Diff line number Diff line
@@ -28,7 +28,7 @@ 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

      ```rust

      let out = dynamo::ListTablesOutput::new();

      out.some_field.unwrap(); // <- partial move, impossible with an accessor

      ```
@@ -52,7 +52,7 @@ long ReadIOs 
long WriteIOs

```

**Rust Output**:

```rust,ignore

```rust

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

#[non_exhaustive]

#[derive(std::clone::Clone, std::cmp::PartialEq)]
@@ -120,10 +120,10 @@ 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.

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 {

design/src/smithy/recursive_shapes.md

+1 −1
Original line number Diff line number Diff line
@@ -13,7 +13,7 @@ struct IntermediateStructure { 
}

```



```rust,ignore

```text

  |

3 | struct TopStructure {

  | ^^^^^^^^^^^^^^^^^^^ recursive type has infinite size

design/src/transport/operation.md

+2 −2
Original line number Diff line number Diff line
@@ -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<Output>`. 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<H, R> {

    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<BatchExecuteStatement> {

    let op = BatchExecuteStatement::new(BatchExecuteStatementInput {