Unverified Commit 5073a25b authored by Harry Barber's avatar Harry Barber Committed by GitHub
Browse files

Various small corrections to server documentation (#2050) 

* Link to super from Handler and OperationService

* Note that structure documentation is from model

* Don't refer to ZSTs in operation_shape.rs opener

* Re-export everything from service to root

* Add reference to root documentation on service

* Fix spelling of MissingOperationsError

* #[doc(hidden)] for opaque_future

* Rename from-parts.md to from_parts.md

* Fix Connected link

* Use S type parameter and service as variable name

* Remove MissingOperation dead code

* Remove Operation header from operation.rs

* Remove reference to closures

* Document ConnectInfo<T> .0

* Add BoxBody documentation

* Rephrase operation.rs documentation

* Reference PluginPipeline from PluginStack

* Move the BoxBody documentation

* Document Plugin associated types

* Add example implementation for Plugin

* Link to plugin module from Plugin

* Improve FromParts/FromRequest documentation

* Remove links to doc(hidden) RuntimeError

* Add link from Upgradable to operation module
parent ee6242cc

codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/rustlang/RustModule.kt

+4 −4
Original line number Diff line number Diff line
@@ -77,10 +77,10 @@ sealed class RustModule { 


        /* Common modules used across client, server and tests */

        val Config = public("config", documentation = "Configuration for the service.")

        val Error = public("error", documentation = "All error types that operations can return.")

        val Model = public("model", documentation = "Data structures used by operation inputs/outputs.")

        val Input = public("input", documentation = "Input structures for operations.")

        val Output = public("output", documentation = "Output structures for operations.")

        val Error = public("error", documentation = "All error types that operations can return. Documentation on these types is copied from the model.")

        val Model = public("model", documentation = "Data structures used by operation inputs/outputs. Documentation on these types is copied from the model.")

        val Input = public("input", documentation = "Input structures for operations. Documentation on these types is copied from the model.")

        val Output = public("output", documentation = "Output structures for operations. Documentation on these types is copied from the model.")

        val Types = public("types", documentation = "Data primitives referenced by other data types.")



        /**

codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/CodegenDelegator.kt

+4 −4
Original line number Diff line number Diff line
@@ -171,11 +171,11 @@ open class RustCrate( 
    }

}



val ErrorsModule = RustModule.public("error", documentation = "All error types that operations can return.")

val ErrorsModule = RustModule.public("error", documentation = "All error types that operations can return. Documentation on these types is copied from the model.")

val OperationsModule = RustModule.public("operation", documentation = "All operations that this crate can perform.")

val ModelsModule = RustModule.public("model", documentation = "Data structures used by operation inputs/outputs.")

val InputsModule = RustModule.public("input", documentation = "Input structures for operations.")

val OutputsModule = RustModule.public("output", documentation = "Output structures for operations.")

val ModelsModule = RustModule.public("model", documentation = "Data structures used by operation inputs/outputs. Documentation on these types is copied from the model.")

val InputsModule = RustModule.public("input", documentation = "Input structures for operations. Documentation on these types is copied from the model.")

val OutputsModule = RustModule.public("output", documentation = "Output structures for operations. Documentation on these types is copied from the model.")



val UnconstrainedModule =

    RustModule.private("unconstrained", "Unconstrained types for constrained shapes.")

codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerOperationShapeGenerator.kt

+4 −3
Original line number Diff line number Diff line
@@ -30,7 +30,7 @@ class ServerOperationShapeGenerator( 


        writer.rustTemplate(

            """

            //! A collection of zero-sized types (ZSTs) representing each operation defined in the service closure.

            //! A collection of types representing each operation defined in the service closure.

            //!

            //! ## Constructing an [`Operation`](#{SmithyHttpServer}::operation::OperationShapeExt)

            //!
@@ -54,8 +54,9 @@ class ServerOperationShapeGenerator( 
            //!

            //! ## Use as Marker Structs

            //!

            //! The [plugin system](#{SmithyHttpServer}::plugin) also makes use of these ZSTs to parameterize

            //! [`Plugin`](#{SmithyHttpServer}::plugin::Plugin) implementations. The traits, such as

            //! The [plugin system](#{SmithyHttpServer}::plugin) also makes use of these

            //! [zero-sized types](https://doc.rust-lang.org/nomicon/exotic-sizes.html##zero-sized-types-zsts) (ZSTs) to

            //! parameterize [`Plugin`](#{SmithyHttpServer}::plugin::Plugin) implementations. The traits, such as

            //! [`OperationShape`](#{SmithyHttpServer}::operation::OperationShape) can be used to provide

            //! operation specific information to the [`Layer`](#{Tower}::Layer) being applied.

            """.trimIndent(),

codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGenerator.kt

+2 −2
Original line number Diff line number Diff line
@@ -44,7 +44,7 @@ open class ServerServiceGenerator( 
    fun render() {

        rustCrate.lib {

            rust("##[doc(inline, hidden)]")

            rust("pub use crate::service::$serviceName;")

            rust("pub use crate::service::{$serviceName, ${serviceName}Builder, MissingOperationsError};")

        }



        rustCrate.withModule(RustModule.operation(Visibility.PRIVATE)) {
@@ -90,7 +90,7 @@ open class ServerServiceGenerator( 


        // TODO(https://github.com/awslabs/smithy-rs/issues/1707): Remove, this is temporary.

        rustCrate.withModule(

            RustModule.LeafModule("service", RustMetadata(visibility = Visibility.PUBLIC, additionalAttributes = listOf(Attribute.DocHidden)), null),

            RustModule.LeafModule("service", RustMetadata(visibility = Visibility.PRIVATE, additionalAttributes = listOf(Attribute.DocHidden)), null),

        ) {

            ServerServiceGeneratorV2(

                codegenContext,

codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt

+5 −3
Original line number Diff line number Diff line
@@ -346,6 +346,8 @@ class ServerServiceGeneratorV2( 


        rustTemplate(

            """

            ///

            /// See the [root](crate) documentation for more information.

            ##[derive(Clone)]

            pub struct $serviceName<S = #{SmithyHttpServer}::routing::Route> {

                router: #{SmithyHttpServer}::routers::RoutingService<#{Router}<S>, #{Protocol}>,