Thanks Salvatore. Some comments inline, but I think we're basically on the same page.
Dan On Thu, Sep 1, 2011 at 3:56 AM, Salvatore Orlando < salvatore.orla...@eu.citrix.com> wrote: > > For this reason, I think it would be good for use to start moving the API > specification in the source code tree, even if other projects, such as > Keystone, decided to take it out of it (it seems it’s going to be moved into > Openstack-manuals project) > Definitely agree. > **** > > ** ** > > As regards the format, all the other projects are using DocBook for API > specification, and RST for man pages and other documentation. It is my > opinion we should be consistent with the other projects, even if reviewing > DocBook XML is not going to be really pleasant. For an example, have a look > at the OS compute dev > guide<http://bazaar.launchpad.net/~annegentle/openstack-manuals/trunk/view/head:/doc/source/docbkx/openstack-compute-api-1.1/os-compute-devguide.xml> > . > Agreed, consistency with other projects is best. If we think they have adopted a bad policy, we should first push to change the openstack-wide policy. In the case of reviews, a reviewer will alway have the option of generating the new docs and reviewing the end result if the impact of a change isn't clear from the XML. > **** > > ** ** > > Another argument being discussed in the Openstack Mailing List is whether > API specification should be generated straight from code (i.e.: docstrings) > or kept separate. **** > > I have to admit I don’t have a strong opinion on this point. You can go to > the Openstack Mailing List and follow the “architect vs developer” > discussion; however, I totally agree with the people who commented that > actually the most important recipient of the API specification are the > users. This leads me to think that what we probably should do for Quantum is > to move the API specification in the source code tree, but keep it separate > from the code, in order to not clutter it with implementation-level details, > which make sense to developers but not to users of the API. > We auto-generate docs from code at Nicira and it definitely has some nice advantages, but to do it in a way that builds nice user facing docs requires a lot of infrastructure in the code-base that we currently don't have for Quantum. I agree with you that just getting the spec doc under source control is the right first step. dan > **** > > ** ** > > Your feedback is, as always, more than welcome.**** > > Best regards, **** > > Salvatore**** > > ** ** > > ** ** > > ** ** > > ** ** > > -- > Mailing list: https://launchpad.net/~netstack > Post to : netstack@lists.launchpad.net > Unsubscribe : https://launchpad.net/~netstack > More help : https://help.launchpad.net/ListHelp > > -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Dan Wendlandt Nicira Networks, Inc. www.nicira.com | www.openvswitch.org Sr. Product Manager cell: 650-906-2650 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- Mailing list: https://launchpad.net/~netstack Post to : netstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~netstack More help : https://help.launchpad.net/ListHelp
