[Ironic][docs][api-sig] Moving API Documentation closer to code

Jeremy Stanley fungi at yuggoth.org
Tue Jan 18 23:03:40 UTC 2022

On 2022-01-19 11:10:58 +1300 (+1300), Steve Baker wrote:
> This proposal is mostly about moving the existing documentation to
> docstrings rather than introspecting the functions/methods
> themselves to auto-generate. There may be some auto-generate
> potential for parameters and output schemas, but whatever is done
> needs to be able to document the API version evolution. The
> benefits of this is more about giving developers proximity to the
> documentation of the REST API they're changing, making
> discrepancies more obvious, and giving reviewers a clear view on
> whether a change is documented correctly.

Correct, I don't recall anyone having tried exactly that approach
yet. It's more akin to what you'd do for documenting a Python
library. I was merely mentioning what other solutions had been
attempted, as an explanation for why I was adding the [api-sig]
subject tag. Apologies if that was unclear.
Jeremy Stanley
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20220118/371d547b/attachment.sig>

More information about the openstack-discuss mailing list