Want mechanism for distinguishing "Rust doc" from "API doc"

[smklein]

At the moment, I believe the two are intermingled: If one wants to document a Rust type with rustdoc, that documentation is implicitly exported as part of the openapi spec. Similarly, if one wants to add openapi documentation, that must be done via Rust comments.

Although it may be a reasonable default for these two documentation targets to have the same source, it's reasonable to want:

• API docs not part of the Rust comments (i.e., they are applicable to the generated type), or
• Rust docs not part of the Open API spec (i.e., they reference other Rust types, or Rust-specific features)

Here's an example: https://github.com/oxidecomputer/omicron/pull/1348/files/b427eded0dfdc10b7c9461a38f110e9c620d0f5f#r918269331

It would be nice to have a mechanism to annotate structs and enums passed through dropshot with "OpenAPI" vs "Rustdoc" specific usage, and filter these before generating the open API spec.

[ahl]

I think you're not going to like this answer, but the intention is that the rustdoc documentation for HTTP API types is intended for consumers of the HTTP API not of the rust crate. Further, the expectation is that a crate would not expose a type both through its HTTP API and its Rust crate interface but rather that it would wrap one or the other if both were needed. (I concede that dropshot itself violates this by exposing types in its public (crate) interface for use in HTTP APIs, but I think that dropshot gets to be a little special.)

In the specific case you've cited--and in omicron generally--I would describe the problem as the types (which are exclusively used for the HTTP API) are very inconsistently documented. Indeed I have on my list to do a scrub of all types and all documentation of the omicron-nexus HTTP API.

For types that are intended to be used as part of the HTTP API and by crate-internal consumers, I would suggest rustdoc (///) for HTTP API types and comments (//) for internal programmer documentation. Indeed, I think the use of rustdoc in these instances is uncommon.

However! I think we could use #[schemars(title = "Some title", description = "Some description")] on #[derive(JsonSchema)]` types to override the use of rustdoc. As described here.