On Tue, Apr 17, 2018 at 02:47:01PM +0200, Andreas Steinel wrote:
> On Tue, Apr 17, 2018 at 2:09 PM, Fabian Grünbichler
> <f.gruenbich...@proxmox.com> wrote:
> > there are some places where we really don't know much more than "some
> > object" (because the API call does a bit too much, and can return one
> > thing or another depending on the code path taken), but in many cases,
> > extending the information should be straight-forward and improve the
> > generated API documentation a lot! so if you do check an API endpoint
> > for your use case and are fairly sure about the returned values, please
> > send a patch..
>
> I'm totally unfamiliar with extjs and I thought this api (the big JSON thing)
> is generated somehow from the code itself as a kind of documentation or
> reference.
it is :) our API framework has a method to dump all the registered API
endpoints, and in our pve-docs repo we have a script that converts that
to json (pve-docs/extractapi.pl). similary, the man pages / synopsis /
help output / bash completion is generated mostly automatically from the
API schema / code. this has the big advantage of keeping the docs in
sync with the actual code without manual intervention (modulo any
manually added examples and long-form descriptions in pve-docs).
> I'm willing to fix things if I found not so well documented things.
> Can you point
> me to the file(s) and package(s) in question to change?
1.) extend the missing/incomplete return values in the API definitions
in the perl code (e.g., pve-storage/PVE/API2/Storage/Status.pm)
2.) build and install the modified package containing the API (e.g.,
pve-storage/libpve-storage-perl)
3.) regenerate the api-viewer files in pve-docs ("make update-static")
4.) build and install pve-docs package
you only need to send the patch from step 1, the rest will be done after
a few changes have been collected in the respective repositories, as
part of the regular package release cycles. so steps 2-4 are just to see
the changes in effect to verify they work as expected ;)
hope this helps. it might help to take a look at some of the better
annotated examples of return values, e.g. GET /cluster/config/join .
if something is unclear, don't hesitate to ask!
_______________________________________________
pve-devel mailing list
pve-devel@pve.proxmox.com
https://pve.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
