Merge pull request #306 from disneystreaming/documentation-polishing

Polish the documentation, use more consistent casing

modules/docs/src/01-overview/01-intro.md

@@ -5,11 +5,10 @@ title: Intro
 
 [Smithy](https://awslabs.github.io/smithy/) is an interface definition language (IDL) provided by AWS. It is protocol agnostic, flexible, and reasonably low surface, which facilitates the writing of tooling around it.
 
-smithy4s is a tool that generates third-party-free, protocol-agnostic scala code from smithy specifications.
+Smithy4s is a tool that generates third-party-free, protocol-agnostic scala code from smithy specifications.
 
 Smithy4s can be used to:
 * quickly derive http/rest servers and clients
 * derive pure-scala AWS clients
 * derive CLI tools
 * and has the potential for much, much more!
-

modules/docs/src/02-the-smithy-idl/01-smithy-idl.md

@@ -15,7 +15,7 @@ Annotations are called `traits` in smithy.
 
 ## The smithy metamodel
 
-In this section, we'll list various available [shapes](https://awslabs.github.io/smithy/quickstart.html#shapes-and-traits) that let you define data and operations in smithy, and how they translate in the Scala code generated by smithy4s.
+In this section, we'll list various available [shapes](https://awslabs.github.io/smithy/quickstart.html#shapes-and-traits) that let you define data and operations in smithy, and how they translate in the Scala code generated by Smithy4s.
 
 ### Primitive types
 
@@ -171,7 +171,7 @@ package object foo {
 }
 ```
 
-`HelloService` is type alias that exposes a normal "functor-shaped" type parameter: we are aware that the most common usecase of smithy4s abides by the "capatibility trait" pattern (or tagless-final), against effect types that probably abide by the cats-effect semantics.
+`HelloService` is type alias that exposes a normal "functor-shaped" type parameter: we are aware that the most common usecase of Smithy4s abides by the "capatibility trait" pattern (or tagless-final), against effect types that probably abide by the cats-effect semantics.
 
 However, the actual interface is `HelloServiceGen`, which has a higher degree of polymorphism. It looks like this:
 
@@ -198,4 +198,4 @@ Keeping track of these parameters is really important for the implementation  in
 
 ### Currently **not** supported (in particular)
 
-Smithy has a `resource` type of shape, that represents CRUD specialised services. It is currently not supported in smithy4s.
+Smithy has a `resource` type of shape, that represents CRUD specialised services. It is currently not supported in Smithy4s.

modules/docs/src/02-the-smithy-idl/02-traits.md

@@ -53,7 +53,7 @@ structure MyStructure {
 }
 ```
 
-### Regarding smithy4s handling of traits
+### Regarding Smithy4s handling of traits
 
 Smithy4s automatically creates corresponding values in the generated Scala code, for all the annotations it finds, whether defined in the smithy prelude, or defined by users.
 

modules/docs/src/03-protocols/01-protocols.md

@@ -1,14 +1,14 @@
 ---
-sidebar_label: Protocols and smithy4s
-title: Protocols and smithy4s
+sidebar_label: Protocols and Smithy4s
+title: Protocols and Smithy4s
 ---
 
-The code generated by smithy4s is strictly **protocol agnostic**, meaning that there is no particular processing to handle HTTP semantics, or JSON semantics in the generated code.
+The code generated by Smithy4s is strictly **protocol agnostic**, meaning that there is no particular processing to handle HTTP semantics, or JSON semantics in the generated code.
 
-Instead, smithy4s relies on a number of highly polymorphic interfaces to communicate with the generated code, and derive JSON codecs out of it, or turn high level user provided code into HTTP services. But in theory, the same generated code can be used conjointly with other serialisation technologies (protobuf for instance) and protocols (gRPC).
+Instead, Smithy4s relies on a number of highly polymorphic interfaces to communicate with the generated code, and derive JSON codecs out of it, or turn high level user provided code into HTTP services. But in theory, the same generated code can be used conjointly with other serialisation technologies (protobuf for instance) and protocols (gRPC).
 
-Protocol specific "hints" (called [traits](../02-the-smithy-idl/02-traits.md))can be added to the smithy models. smithy4s accurately renders corresponding values, and allows for their retrieval via the polymorphic interfaces. This is how HTTP semantics can be derived from the generated code, for instance.
+Protocol specific "hints" (called [traits](../02-the-smithy-idl/02-traits.md))can be added to the smithy models. Smithy4s accurately renders corresponding values, and allows for their retrieval via the polymorphic interfaces. This is how HTTP semantics can be derived from the generated code, for instance.
 
 Smithy4s is also not tied to any third-party library, and users could provide integrations with existing libraries on their own side, or come up with new interesting usecases.
 
-However, smithy4s provides a few out-of-the-box integrations that are described in this section.
+However, Smithy4s provides a few out-of-the-box integrations that are described in this section.

modules/docs/src/03-protocols/03-aws/01-aws.md

@@ -4,11 +4,11 @@ sidebar_label: AWS
 
 **WARNING: THIS IS EXPERIMENTAL, DO NOT NOT EXPECT PRODUCTION READINESS**
 
-smithy4s provides functions to create AWS clients from generated code. At the time of writing this, smithy4s is only able to derive clients for AWS services that use the [AWS Json 1.0/1.1 protocol](https://awslabs.github.io/smithy/1.0/spec/aws/index.html?highlight=aws%20protocols#aws-protocols).
+Smithy4s provides functions to create AWS clients from generated code. At the time of writing this, smithy4s is only able to derive clients for AWS services that use the [AWS Json 1.0/1.1 protocol](https://awslabs.github.io/smithy/1.0/spec/aws/index.html?highlight=aws%20protocols#aws-protocols).
 
 The AWS smithy specs (that are written in json syntax) can be found in some of the [official SDKs](https://github.com/aws/aws-sdk-js-v3/tree/main/codegen/sdk-codegen/aws-models) published by AWS. These `.json files` can be understood by smithy4s, just like `.smithy`, and can be used to generate code. Just copy/paste them in your project.
 
-We (the smithy4s maintainers) **do not** intend to publish pre-generated artifacts containing the AWS clients, there's a lot of nuance there and maintainance burden that we do not have the capacity to assume. In particular, backward binary compatibility of the generated code is impossible to guarantee at this time.
+We (the Smithy4s maintainers) **do not** intend to publish pre-generated artifacts containing the AWS clients, there's a lot of nuance there and maintainance burden that we do not have the capacity to assume. In particular, backward binary compatibility of the generated code is impossible to guarantee at this time.
 
 #### Setup
 

modules/docs/src/04-codegen/01-customisation.md

@@ -7,7 +7,7 @@ Smithy4s is opinionated in what the generated code look like, there are a few th
 
 #### Packed inputs
 
-By default, smithy4s generates methods the parameters of which map to the fields of the input structure of the corresponding operation.
+By default, Smithy4s generates methods the parameters of which map to the fields of the input structure of the corresponding operation.
 
 For instance :
 
@@ -65,7 +65,7 @@ trait PackedInputServiceGen[F[_]] {
 
 #### ADT Member Trait
 
-The default behavior of smithy4s when rendering unions that target structures is to render the structure
+The default behavior of Smithy4s when rendering unions that target structures is to render the structure
 in a separate file from the union that targets it. This makes sense if the structure is used in other
 contexts other than the union. However, it also causes an extra level of nesting within the union.
 This is because the union will create another case class to contain your structure case class.
@@ -131,7 +131,7 @@ The structure annotated with `adtMember` (e.g. `InStoreOrder`) also must not be
 structures or unions in the model. There is a validator that will make sure these requirements are met
 whenever the `adtMember` trait is in use.
 
-Note: The `adtMember` trait has NO impact on the serialization/deserialization behaviors of smithy4s.
+Note: The `adtMember` trait has NO impact on the serialization/deserialization behaviors of Smithy4s.
 The only thing it changes is what the generated code looks like. This is accomplished by keeping the
 rendered schemas equivalent, even if the case class is rendered in a different place.
 

modules/docs/src/05-design/01-design.md

@@ -3,10 +3,10 @@ sidebar_label: General design principles
 title: General design principles
 ---
 
-Before we dive in to the design elements, it is important to state that smithy4s is designed with the following constraints :
+Before we dive in to the design elements, it is important to state that Smithy4s is designed with the following constraints :
 
-* **optimised for number of usecases**: smithy4s is **not** (just) an http/json library, it can/could be used for a great many things, such as AWS SDKs, CLIs, UIs, etc.
-Therefore, following the protocol-agnostic nature of smithy, the code generated by smithy4s is not biased towards any protocol or serialisation mechanism, nor any runtime or Scala version.
+* **optimised for number of usecases**: Smithy4s is **not** (just) an http/json library, it can/could be used for a great many things, such as AWS SDKs, CLIs, UIs, etc.
+Therefore, following the protocol-agnostic nature of smithy, the code generated by Smithy4s is not biased towards any protocol or serialisation mechanism, nor any runtime or Scala version.
 * **optimised for correctness over compatibility**: there is strictly no guarantee made regarding backward compatibility of the generated code when users evolve their smithy schemas.
 Therefore, users are expected to regenerate the code at use-site, instead of relying on artifacts that would contain the generated code... However, users do get idiomatic Scala code, including case classes / sealed traits (which are notoriously hard to evolve in binary compatible ways), and this generated code correctly reflects the smithy specifications.
 * **decoupled from third-party libraries**: the generated code depends only on smithy4s-core for compilation, which does not pull third-party dependencies (not even a general purpose libraries that the maintainers love, like cats)