Open Stack

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 at 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