<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Jul 8, 2015 at 9:48 PM, GHANSHYAM MANN <span dir="ltr"><<a href="mailto:ghanshyammann@gmail.com" target="_blank">ghanshyammann@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span class="">On Thu, Jul 9, 2015 at 9:39 AM, Ken'ichi Ohmichi <<a href="mailto:ken1ohmichi@gmail.com">ken1ohmichi@gmail.com</a>> wrote:<br>
> 2015-07-08 16:42 GMT+09:00 Ken'ichi Ohmichi <<a href="mailto:ken1ohmichi@gmail.com">ken1ohmichi@gmail.com</a>>:<br>
>> 2015-07-08 14:07 GMT+09:00 GHANSHYAM MANN <<a href="mailto:ghanshyammann@gmail.com">ghanshyammann@gmail.com</a>>:<br>
>>> On Wed, Jul 8, 2015 at 12:27 PM, Ken'ichi Ohmichi <<a href="mailto:ken1ohmichi@gmail.com">ken1ohmichi@gmail.com</a>> wrote:<br>
>>>><br>
>>>> By defining all parameters on each method like update_quota_set(), it<br>
>>>> is easy to know what parameters are available from caller/programer<br>
>>>> viewpoint.<br>
>>><br>
>>> I think this can be achieved with former approach also by defining all<br>
>>> expected param in doc string properly.<br>
>><br>
>> You are exactly right.<br>
>> But current service clients contain 187 methods *only for Nova* and<br>
>> most methods don't contain enough doc string.<br>
>> So my previous hope which was implied was we could avoid writing doc<br>
>> string with later approach.<br>
><br>
> I am thinking it is very difficult to maintain doc string of REST APIs<br>
> in tempest-lib because APIs continue changing.<br>
> So instead of doing it, how about putting the link of official API<br>
> document[1] in tempest-lib and concentrating on maintaining official<br>
> API document?<br>
> OpenStack APIs are huge now and It doesn't seem smart to maintain<br>
> these docs at different places.<br>
><br>
<br>
</span>++, this will be great. Even API links can be provided in both class<br>
doc string as well as each method doc string (link to specific API).<br>
This will improve API ref docs quality and maintainability.<br></blockquote><div><br></div><div>Agreed, though I also want to point you to this doc specification. We hope it will help with the maintenance of the API docs. </div><div><br></div><div><a href="https://review.openstack.org/#/c/177934/">https://review.openstack.org/#/c/177934/</a><br></div><div><br></div><div>I also want Tempest maintainers to start thinking about how a diff comparison can help with reviews of any changes to the API itself. We have a proof of concept and need to do additional work to ensure it works for multiple OpenStack APIs.</div><div>Thanks,</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<span class="im"><br>
> Thanks<br>
> Ken Ohmichi<br>
><br>
> ---<br>
> [1]: <a href="http://developer.openstack.org/api-ref.html" rel="noreferrer" target="_blank">http://developer.openstack.org/api-ref.html</a><br>
><br>
> __________________________________________________________________________<br>
> OpenStack Development Mailing List (not for usage questions)<br>
> Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br>
<br>
<br>
</span><span class="im">--<br>
Thanks & Regards<br>
Ghanshyam Mann<br>
<br>
</span><div class=""><div class="h5">__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div>Anne Gentle</div><div>Rackspace</div><div>Principal Engineer</div><div><a href="http://www.justwriteclick.com" target="_blank">www.justwriteclick.com</a></div></div></div>
</div></div>