I understand more clearly now the reason for the initial choice of keeping the documentation and code separate. Any solution to address the maintainability problem that has arisen as a consequence, should be able to maintain API version history. Auto-documentation is another approach we could try, but I think it would not offer many features or be very descriptive. (The output might be very boilerplate-looking).
On Wed, Jan 19, 2022 at 4:10 AM Jeremy Stanley fungi@yuggoth.org wrote:
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