<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Fri, May 19, 2017 at 8:00 AM, Sean Dague <span dir="ltr"><<a href="mailto:sean@dague.net" target="_blank">sean@dague.net</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="HOEnZb"><div class="h5">On 05/19/2017 08:36 AM, Monty Taylor wrote:<br>
> On 05/17/2017 10:14 AM, Joe Topjian wrote:<br>
>><br>
>><br>
>> On Tue, May 16, 2017 at 4:13 PM, Monty Taylor <<a href="mailto:mordred@inaugust.com">mordred@inaugust.com</a><br>
>> <mailto:<a href="mailto:mordred@inaugust.com">mordred@inaugust.com</a>>> wrote:<br>
>><br>
>>     Hey all!<br>
>><br>
>>     I read the API docs A LOT. (thank you to all of you who have worked<br>
>>     on writing them)<br>
>><br>
>>     As I do, a gotcha I hit up against a non-zero amount is mapping the<br>
>>     descriptions of the response parameters to the form of the response<br>
>>     itself. Most of the time there is a top level parameter under which<br>
>>     either an object or a list resides, but the description lists list<br>
>>     the top level and the sub-parameters as siblings.<br>
>><br>
>>     So I wrote a patch to os-api-ref taking a stab at providing a way to<br>
>>     show things a little differently:<br>
>><br>
>>     <a href="https://review.openstack.org/#/c/464255/" rel="noreferrer" target="_blank">https://review.openstack.org/#<wbr>/c/464255/</a><br>
>>     <<a href="https://review.openstack.org/#/c/464255/" rel="noreferrer" target="_blank">https://review.openstack.org/<wbr>#/c/464255/</a>><br>
>><br>
>>     You can see the output here:<br>
>><br>
>><br>
>> <a href="http://docs-draft.openstack.org/55/464255/5/check/gate-nova-api-ref-src/f02b170//api-ref/build/html/" rel="noreferrer" target="_blank">http://docs-draft.openstack.<wbr>org/55/464255/5/check/gate-<wbr>nova-api-ref-src/f02b170//api-<wbr>ref/build/html/</a><br>
>><br>
>><br>
>> <<a href="http://docs-draft.openstack.org/55/464255/5/check/gate-nova-api-ref-src/f02b170//api-ref/build/html/" rel="noreferrer" target="_blank">http://docs-draft.openstack.<wbr>org/55/464255/5/check/gate-<wbr>nova-api-ref-src/f02b170//api-<wbr>ref/build/html/</a>><br>
>><br>
>><br>
>>     If you go expand either the GET / or the GET /servers/details<br>
>>     sections and go to look at their Response sections, you can see it<br>
>>     in action.<br>
>><br>
>>     We'd like some feedback on impact from humans who read the API docs<br>
>>     decently regularly...<br>
>><br>
>>     The questions:<br>
>><br>
>>     - Does this help, hurt, no difference?<br>
>><br>
>><br>
>> It helps. It seems noisy at first glance, but the information being<br>
>> denoted is important. It's one of those situations where once you start<br>
>> reading deeper into the information, this kind of markup makes the API<br>
>> more understandable more quickly.<br>
><br>
> Awesome. Thanks!<br>
><br>
>>     - servers[].name - servers is a list, containing objects with a name<br>
>>     field. Good or bad?<br>
>>     - servers[].addresses.$network-<wbr>name - addresses is an object and the<br>
>>     keys of the object are the name of the network in question.<br>
>><br>
>><br>
>> Again, these seem noisy at first, but having parsed complex paths,<br>
>> especially the above address info, by dumping variables too many times,<br>
>> I really appreciate the above syntax.<br>
>><br>
>> Going even further:<br>
>><br>
>> servers[].addresses.$network-<wbr>name[].OS-EXT-IPS-MAC:mac_addr<br>
>><br>
>> looks a mess, but I can see how exactly to navigate to the leaf as well<br>
>> as understand what types make up the path. Being able to succinctly<br>
>> (relatively/subjectively speaking) describe something like the above is<br>
>> very helpful. This definitely gets my support.<br>
><br>
> Sweet. thanks for the feedback! I just pushed up a new rev yesterday<br>
> based on some feedback from Anne:<br>
><br>
> <a href="http://docs-draft.openstack.org/55/464255/5/check/gate-nova-api-ref-src/f02b170//api-ref/build/html/" rel="noreferrer" target="_blank">http://docs-draft.openstack.<wbr>org/55/464255/5/check/gate-<wbr>nova-api-ref-src/f02b170//api-<wbr>ref/build/html/</a><br>
<br>
</div></div><a href="http://docs-draft.openstack.org/55/464255/7/check/gate-nova-api-ref-src/88a33cc//api-ref/build/html/" rel="noreferrer" target="_blank">http://docs-draft.openstack.<wbr>org/55/464255/7/check/gate-<wbr>nova-api-ref-src/88a33cc//api-<wbr>ref/build/html/</a><br>
is actually the revision with the <strong> tags.</blockquote><div><br></div><div>+1 on the <strong> tags. </div></div></div></div>