Open Stack

Hi Anne,

2015-07-09 12:22 GMT+09:00 Anne Gentle <annegentle at justwriteclick.com>:
> On Wed, Jul 8, 2015 at 9:48 PM, GHANSHYAM MANN <ghanshyammann at gmail.com>
> wrote:
>> On Thu, Jul 9, 2015 at 9:39 AM, Ken'ichi Ohmichi <ken1ohmichi at gmail.com>
>> wrote:
>> > 2015-07-08 16:42 GMT+09:00 Ken'ichi Ohmichi <ken1ohmichi at gmail.com>:
>> >> 2015-07-08 14:07 GMT+09:00 GHANSHYAM MANN <ghanshyammann at gmail.com>:
>> >>> On Wed, Jul 8, 2015 at 12:27 PM, Ken'ichi Ohmichi
>> >>> <ken1ohmichi at gmail.com> wrote:
>> >>>>
>> >>>> By defining all parameters on each method like update_quota_set(), it
>> >>>> is easy to know what parameters are available from caller/programer
>> >>>> viewpoint.
>> >>>
>> >>> I think this can be achieved with former approach also by defining all
>> >>> expected param in doc string properly.
>> >>
>> >> You are exactly right.
>> >> But current service clients contain 187 methods *only for Nova* and
>> >> most methods don't contain enough doc string.
>> >> So my previous hope which was implied was we could avoid writing doc
>> >> string with later approach.
>> >
>> > I am thinking it is very difficult to maintain doc string of REST APIs
>> > in tempest-lib because APIs continue changing.
>> > So instead of doing it, how about putting the link of official API
>> > document[1] in tempest-lib and concentrating on maintaining official
>> > API document?
>> > OpenStack APIs are huge now and It doesn't seem smart to maintain
>> > these docs at different places.
>> >
>>
>> ++, this will be great. Even API links can be provided in both class
>> doc string as well as each method doc string (link to specific API).
>> This will improve API ref docs quality and maintainability.
>
>
> Agreed, though I also want to point you to this doc specification. We hope
> it will help with the maintenance of the API docs.
>
> https://review.openstack.org/#/c/177934/
>
> 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.

Thanks for your feedback,
That will be a big step for improving the API docs, I also like to
join for working together.

Thanks
Ken Ohmichi