Fix some docs formatting

Author: gjcairo

Sources/GRPCCore/Documentation.docc/Articles/Generating-stubs.md

@@ -2,7 +2,9 @@
 
 Learn how to generate stubs for gRPC Swift from a service defined using the Protocol Buffers IDL.
 
-## Using protoc
+## Overview
+
+### Using protoc
 
 If you've used Protocol Buffers before then generating gRPC Swift stubs should be simple. If you're
 unfamiliar with Protocol Buffers then you should get comfortable with the concepts before
@@ -45,7 +47,7 @@ protoc \
   --grpc-swift_out=.
 ```
 
-### Generator options
+#### Generator options
 
 | Name                      | Possible Values                            | Default    | Description                                              |
 |---------------------------|--------------------------------------------|------------|----------------------------------------------------------|
@@ -67,7 +69,7 @@ allows you to specify a mapping from `.proto` files to the Swift module they are
 allows the code generator to add appropriate imports to your generated stubs. This is described in
 more detail in the [SwiftProtobuf documentation](https://github.com/apple/swift-protobuf/blob/main/Documentation/PLUGIN.md).
 
-### Building the plugin
+#### Building the plugin
 
 > The version of `protoc-gen-grpc-swift` you use mustn't be newer than the version of
 > the `grpc-swift-protobuf` you're using.

Sources/GRPCCore/Documentation.docc/Development/Benchmarks.md

@@ -1,5 +1,7 @@
 # Benchmarks
 
+This article discusses benchmarking in `grpc-swift`.
+
 ## Overview
 
 Benchmarks for this package are in a separate Swift Package in the `Performance/Benchmarks`

Sources/GRPCCore/Documentation.docc/Development/Design.md

@@ -14,7 +14,9 @@ mapping a call onto a stream and dealing with serialization. The highest level
 of abstraction is the _stub_ layer which provides client and server interfaces
 generated from an interface definition language (IDL).
 
-## Transport
+## Overview
+
+### Transport
 
 The transport layer provides a bidirectional communication channel with a remote
 peer which is typically long-lived.
@@ -42,7 +44,7 @@ The vast majority of users won't need to implement either of these protocols.
 However, many users will need to create instances of types conforming to these
 protocols to create a server or client, respectively.
 
-### Server transport
+#### Server transport
 
 The ``ServerTransport`` is responsible for the server half of a transport. It
 listens for new gRPC streams and then processes them. This is achieved via the
@@ -57,7 +59,7 @@ Note that the server transport doesn't include the idea of a "connection". While
 an HTTP/2 server transport will in all likelihood have multiple connections open
 at any given time, that detail isn't surfaced at this level of abstraction.
 
-### Client transport
+#### Client transport
 
 While the server is responsible for handling streams, the ``ClientTransport`` is
 responsible for creating them. Client transports will typically maintain a
@@ -83,7 +85,7 @@ may be retried. Some of this is exposed via the ``ClientTransport`` as
 the ``ClientTransport/retryThrottle`` and
 ``ClientTransport/config(forMethod:)``.
 
-### Streams
+#### Streams
 
 Both client and server transport protocols use ``RPCStream`` to represent
 streams of information. Each RPC can be thought of as having two logical
@@ -122,7 +124,7 @@ and indicates the final outcome of an RPC. It includes a ``Status/Code-swift.str
 and string describing the final outcome while the ``Metadata`` may contain additional
 information about the RPC.
 
-## Call
+### Call
 
 The "call" layer builds on top the transport layer to map higher level RPCs calls on
 to streams. It also implements transport-agnostic functionality, like serialization
@@ -139,7 +141,7 @@ provides support for [SwiftProtobuf](https://github.com/apple/swift-protobuf) by
 implementing serializers and a code generator for the Protocol Buffers
 compiler, `protoc`.
 
-### Interceptors
+#### Interceptors
 
 This layer also provides client and server interceptors allowing you to modify requests
 and responses between the caller and the network. These are implemented as
@@ -152,7 +154,7 @@ Naturally, the interceptors APIs are `async`.
 Interceptors are registered directly with the ``GRPCClient`` and ``GRPCServer`` and
 can either be applied to all RPCs or to specific services.
 
-### Client
+#### Client
 
 The call layer includes  a concrete ``GRPCClient`` which provides API to execute all
 four types of RPC against a ``ClientTransport``. These methods are:
@@ -178,7 +180,7 @@ which will stop new RPCs from starting (by failing them with
 Existing work can be stopped more abruptly by cancelling the task where
 ``GRPCClient/run()`` is executing.
 
-### Server
+#### Server
 
 ``GRPCServer`` is provided by the call layer to host services for a given
 transport. Beyond creating the server it has a very limited API surface: it has
@@ -188,7 +190,7 @@ can initiate graceful shutdown by calling ``GRPCServer/beginGracefulShutdown()``
 which will stop new RPCs from being handled but will let existing RPCs run to
 completion. Cancelling the task will close the server more abruptly.
 
-## Stub
+### Stub
 
 The stub layer is the layer which most users interact with. It provides service
 specific interfaces generated from an interface definition language (IDL) such
@@ -204,7 +206,7 @@ However, the stub layer is optional, users may choose to not use it and
 construct clients and services manually. A gRPC proxy, for example, would not
 use the stub layer.
 
-### Server stubs
+#### Server stubs
 
 Users implement services by conforming a type to a generated service `protocol`.
 Each service has three protocols generated for it:
@@ -308,7 +310,7 @@ refines the ``RegistrableRPCService`` protocol. This `protocol` has a single
 requirement for registering methods with an ``RPCRouter``. A default
 implementation of this method is also provided.
 
-### Client stubs
+#### Client stubs
 
 Generated client code is split into a `protocol` and a concrete `struct`
 implementing the `protocol`. An example of the client protocol is:

Sources/GRPCCore/Documentation.docc/Documentation.md

@@ -5,7 +5,9 @@ A gRPC library for Swift written natively in Swift.
 > 🚧 This module is part of gRPC Swift v2 which is under active development and in the pre-release
 > stage.
 
-## Package structure
+## Overview
+
+### Package structure
 
 gRPC Swift is distributed across multiple Swift packages. These are:
 
@@ -32,7 +34,7 @@ gRPC Swift is distributed across multiple Swift packages. These are:
 This package, and this module (``GRPCCore``) in particular, include higher level documentation such
 as tutorials.
 
-## Modules in this package
+### Modules in this package
 
 - ``GRPCCore`` (this module) contains core abstractions, currency types and runtime components
   for gRPC Swift.