documentation: Document the 1.0 API

[sameo]

The virtcontainers godoc [1] does not highlight the 1.0 top level API in a readable and clear way. This API documentation attempts to provide a top to bottom description of the virtcontainers 1.0 API.

[1] https://godoc.org/github.com/containers/virtcontainers

Signed-off-by: Samuel Ortiz sameo@linux.intel.com

[jodh-intel]

This looks really useful to me. My only question/reservation is how we can ensure that doc is updated as and when changes are made to the API. Was is entirely hand-written or is it atleast partly generated?

I'm also wondering if we could create (auto-generate) some state/sequence diagrams (maybe there is a tool like Doxygen for go that could do this for us)?

[jodh-intel]

A diagram showing how pods and containers differ would also be useful if that could be added somehow.

[sameo]

@jodh-intel @grahamwhaley

My only question/reservation is how we can ensure that doc is updated as and when changes are made to the API. Was is entirely hand-written or is it atleast partly generated?

It was entirely hand written. The API that's described here is the 1.0 one, and at least we know we will not push backward incompatible changes without changing the version number. So those changes at least won't have to be propagated to the document.

The next step is to use godoc instead of manually generating this documentation and I think the proper way to do so would be to create a specific api package for virtcontainers and possibly split the code into more packages. Right now, our entire exported API is under the virtcontainers package and as a result the generated godoc is messy. I'll look into that next.

[jodh-intel]

Hi @sameo - makes sense to me. Thanks for putting this together!

lgtm