Open Stack

Hey all!

I read the API docs A LOT. (thank you to all of you who have worked on 
writing them)

As I do, a gotcha I hit up against a non-zero amount is mapping the 
descriptions of the response parameters to the form of the response 
itself. Most of the time there is a top level parameter under which 
either an object or a list resides, but the description lists list the 
top level and the sub-parameters as siblings.

So I wrote a patch to os-api-ref taking a stab at providing a way to 
show things a little differently:

https://review.openstack.org/#/c/464255/

You can see the output here:

http://docs-draft.openstack.org/55/464255/5/check/gate-nova-api-ref-src/f02b170//api-ref/build/html/

If you go expand either the GET / or the GET /servers/details sections 
and go to look at their Response sections, you can see it in action.

We'd like some feedback on impact from humans who read the API docs 
decently regularly...

The questions:

- Does this help, hurt, no difference?
- servers[].name - servers is a list, containing objects with a name 
field. Good or bad?
- servers[].addresses.$network-name - addresses is an object and the 
keys of the object are the name of the network in question.

Thanks!
Monty