Feedback for Generated Code

[davidbarsky]

As requested by @rcoh; here are few things I've noticed from reading the documentation.

• dynamo::model::FailureException is the only type in the model module that represents an error. I think this happened because the underlying Smithy definition might be incorrect.
  • Generally speaking, I don't think that "Exception" shouldn't appear in any Rust code
• The operation module is noisy from the builder module [appendix one]. It also hides the actual input operations below the documentation's fold. Unfortunately, applying #[doc(hidden)] to a module applies to all nested modules and exports, which means that the builder options are hidden: rustdoc: doc(hidden) also hides re-exports rust-lang/rust#59368
• When documenting input structs, consider using the operation's documentation instead of the input object's documentation [appendix two]. Input structs are the customer's entrypoint to the service, not the operation itself. With a sans-io interface, there's no place to document operations, which often serve as the why of a service's operation.
• The separate impl blocks for inputs without different generic bounds feel off to me [appendix three]. I'd unify the two.
  • I'm not sure that an assemble associated function is necessary for non-streaming operations, but I believe this relates to the (somewhat) open design question around (de)serialization.
• Intra-doc links don't resolve to a URL. You might need to define a [docs-url] in the root of each crate: [WIP] Add cargo-deadlinks to CI tokio-rs/tracing#1078 (comment).
  • Consider using the tokio-rs/tracing repo as an example for documentation configuration. Members of the rustdoc team have use tokio-rs/tracing as a testbed for unstable features.

Appendix

Appendix One

Appendix Two

Appendix Three

[jdisanti]

We should take another pass on this feedback before GA. Adding it to the milestone.