Add missing newlines in api docstrings. #9562
Conversation
At the moment, some docstrings in the generated docs lack newlines, and string together multiple sentences without punctuation. For example, the `provisioned` field in the `silo_utilization_list` method is a bit garbled: https://docs.oxide.computer/api/silo_utilization_list. > Accounts for resources allocated by in silos like CPU or memory for running > instances and storage for disks and snapshots Note that CPU and memory > resources associated with a stopped instances are not counted here This patch adds the missing newlines and punctuation to make this docstring readable. Note that these changes won't show up in the generated docs until we cut a new release. Note: if this change makes sense, I'll also ask Claude to review all docstrings in this crate for similar issues.
| /// Note that CPU and memory resources associated with a stopped instances are not counted here | ||
| /// Accounts for resources allocated by in silos like CPU or memory for running instances and storage for disks and snapshots. | ||
| /// | ||
| /// Note that CPU and memory resources associated with a stopped instances are not counted here. |
|
Totally on board. You will have to regen the openapi schema with |
jmcarp
force-pushed
the
jmcarp/docstring-newlines
branch
from
80f0aff to
151c22c
Compare
|
Ok, I had Claude make more edits, and checked in a markdown file to make these rules at least somewhat repeatable.
I might be misunderstanding, but I think this isn't enough. I couldn't get the xtask to update the generated docs until I added a new (fake) version in nexus/external-api/src/lib.rs. Is there a different workflow for making docs-only changes to the openapi spec? |
|
A reasonable expectation, but I think that's how it's supposed to work. |
|
The change in #9546 means that you'll be asked to add a new version for non-semantic changes. |
At the moment, some docstrings in the generated docs lack newlines, and string together multiple sentences without punctuation. For example, the
provisionedfield in thesilo_utilization_listmethod is a bit garbled: https://docs.oxide.computer/api/silo_utilization_list.This patch adds the missing newlines and punctuation to make this docstring readable. Note that these changes won't show up in the generated docs until we cut a new release.
Note: if this change makes sense, I'll also ask Claude to review all docstrings in this crate for similar issues.
cc @david-crespo in case this is relevant to your interests (docs style guide, making Claude do things).