[Ironic][docs][api-sig] Moving API Documentation closer to code
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.
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 963 bytes
Desc: not available
More information about the openstack-discuss