Hi Anne, 2015-07-09 12:22 GMT+09:00 Anne Gentle <[email protected]>: > On Wed, Jul 8, 2015 at 9:48 PM, GHANSHYAM MANN <[email protected]> > wrote: >> On Thu, Jul 9, 2015 at 9:39 AM, Ken'ichi Ohmichi <[email protected]> >> wrote: >> > 2015-07-08 16:42 GMT+09:00 Ken'ichi Ohmichi <[email protected]>: >> >> 2015-07-08 14:07 GMT+09:00 GHANSHYAM MANN <[email protected]>: >> >>> On Wed, Jul 8, 2015 at 12:27 PM, Ken'ichi Ohmichi >> >>> <[email protected]> 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 __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
