Open Stack

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,
Anne


>
> > Thanks
> > Ken Ohmichi
> >
> > ---
> > [1]: http://developer.openstack.org/api-ref.html
> >
> >
> __________________________________________________________________________
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe:
> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
>
> --
> Thanks & Regards
> Ghanshyam Mann
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150708/cc5e6965/attachment.html>