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