Skip to content

Commit

Permalink
Fix a few rendering issues in the design docs (smithy-lang#1787)
Browse files Browse the repository at this point in the history
* 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.
  • Loading branch information
Luca Palmieri authored Sep 30, 2022
1 parent 4cfac14 commit 4c5cbc3
Show file tree
Hide file tree
Showing 3 changed files with 15 additions and 15 deletions.
24 changes: 12 additions & 12 deletions design/src/smithy/aggregate_shapes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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)]
Expand Down Expand Up @@ -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`
Expand All @@ -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 {
Expand Down
2 changes: 1 addition & 1 deletion design/src/smithy/recursive_shapes.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ struct IntermediateStructure {
}
```

```rust,ignore
```text
|
3 | struct TopStructure {
| ^^^^^^^^^^^^^^^^^^^ recursive type has infinite size
Expand Down
4 changes: 2 additions & 2 deletions design/src/transport/operation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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 {
Expand Down

0 comments on commit 4c5cbc3

Please sign in to comment.