Document buildstructor builders

[SimonSapin]

Part of https://github.com/apollographql/router/issues/799

Builders generated by buildstructor have the nice feature of checking at compile-time that required data is indeed provided. However this makes the generated builder type rather complex and hard to understand in rustdoc. For this reason, builder types are currently generated in private modules so that their methods are not visible at all in rustdoc.

Ideally buildstructor would generate something that renders nicely in rustdoc, but that seems contradictory with compile-time checking of required data. So instead, let’s document builder methods in Markdown in builder constructor doc-comments.

Public builders as of d1be87de:

• [x] Executable
• [x] graphql::Error
• [ ] graphql::Request
• [ ] graphql::Response
• [ ] graphql::IncrementalResponse
• [x] RouterHttpServer
• [ ] execution::Request
• [ ] subgraph::Request
• [ ] subgraph::Response
• [ ] supergraph::Request
• [ ] supergraph::Response

---

Let’s take an example from apollo-router/src/router.rs:

#[buildstructor::buildstructor]
impl RouterHttpServer {
    /// (actual doc-comment below)
    #[builder(visibility = "pub", entry = "builder", exit = "start")]
    fn start(
        schema: SchemaSource,
        configuration: Option<ConfigurationSource>,
        shutdown: Option<ShutdownSource>,
    ) -> RouterHttpServer {
    }
}

Buildstructor will generate a public RouterHttpServer::builder that returns a builder, with docs copied from the private RouterHttpServer::start. So we should write docs with something like “returns a builder that does X” rather than “Does X”, and documents all methods of the builder type in a bullet list:

• Those setting one parameter for the constructor, detailing if it’s required or optional
• For collection/map parameters, the method that builds them up one item at a time
• Mention impl Into if applicable. It’s super useful but not easily discoverable
• Use rustdoc autolinks for parameter types. The syntax is [`name`] or [`path::to::name`] or [`name`][path::to::name]. Paths are resolved based on what imports are in scope. Markdown syntax cannot be used inside backtick-delimited inline code, a work-around is to end inline code just before the auto-link, have another one inside, and start a third just after.
• One last bullet list item for the builder "exit" method.

Putting it all together:

    /// Returns a builder to start an HTTP server in a separate Tokio task.
    ///
    /// Builder methods:
    ///
    /// * `.schema(impl Into<`[`SchemaSource`]`>)`
    ///   Required.
    ///   Specifies where to find the supergraph schema definition.
    ///   Some sources support hot-reloading.
    ///
    /// * `.configuration(impl Into<`[`ConfigurationSource`]`>)`
    ///   Optional.
    ///   Specifies where to find the router configuration.
    ///   If not provided, the default configuration as with an empty YAML file.
    ///
    /// * `.shutdown(impl Into<`[`ShutdownSource`]`>)`
    ///   Optional.
    ///   Specifies when the server should gracefully shut down.
    ///   If not provided, the default is [`ShutdownSource::CtrlC`].
    ///
    /// * `.start()`
    ///   Finishes the builder,
    ///   starts an HTTP server in a separate Tokio task,
    ///   and returns a `RouterHttpServer` handle.
    ///
    /// The server handle can be used in multiple ways.
    /// As a [`Future`], it resolves to `Result<(), `[`ApolloRouterError`]`>`
    /// either when the server has finished gracefully shutting down
    /// or when it encounters a fatal error that prevents it from starting.
    ///
    /// If the handle is dropped before being awaited as a future,
    /// a graceful shutdown is triggered.
    /// In order to wait until shutdown finishes,
    /// use the [`shutdown`][Self::shutdown] method instead.