Make module docs customizable and update mod docs for crate reorg #2418
Conversation
jdisanti
force-pushed
the
jdisanti-reorganize-doc-fixes
branch
3 times, most recently
from
ce42828 to
9b63b2f
Compare
|
A new generated diff is ready to view.
A new doc preview is ready to view. |
jdisanti
force-pushed
the
jdisanti-reorganize-doc-fixes
branch
from
9b63b2f to
241771d
Compare
|
A new generated diff is ready to view.
A new doc preview is ready to view. |
| override fun docs(module: RustModule.LeafModule): String? = when (module) { | ||
| ServerRustModule.Error -> "All error types that operations can return. Documentation on these types is copied from the model." | ||
| ServerRustModule.Operation -> "All operations that this crate can perform." | ||
| // TODO(ServerTeam): Document this module (I don't have context) |
There was a problem hiding this comment.
This module has a decent amount of documentation. We render it in ServerOperationShapeGenerator.kt via a writer.rustTemplate. This is similar to our root docs found in ServerServiceGenerator.kt.
For this reason I think perhaps the docs method should return a Writable? and the dependencies templated in it should be added to the dev-dependencies rather than the normal dependencies.
There was a problem hiding this comment.
Was actually just refactoring it to be that way in #2432 in order to fix CI. Can we ship this and have that refactor be taken care of there?
There was a problem hiding this comment.
One additional thing to note during doc generation refactors is that I think it'd be nicer to generate the docs in the actual module rather than on the mod statement for the following reasons:
- Huge docs won't crowd their parent module
- They would be more discoverable for developers
- Intra-doc links would be easier
There was a problem hiding this comment.
Yeah, I definitely agree that would be better. Given how our module writing system currently works, though, this will require a significant refactor since it will require buffering and separating writables to output into different logical sections. Definitely something to strive towards in the long term, but will require a considerable amount of work.
|
A new generated diff is ready to view.
A new doc preview is ready to view. |
Motivation and Context
This is needed to correct the module docs behind the
enableNewCrateOrganizationSchemefeature flag, although it can also be used to allow for codegen decorators to change or augment module documentation (e.g., maybe the AWS SDK adds additional examples/links/etc), and for the service model and codegen config to be incorporated into those docs.By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.