On Tue, Feb 10, 2015 at 1:57 PM, Min Pae <sputni...@gmail.com> wrote: > I think most people would agree documentation is a good thing, and > consistency is generally a good thing… is there an accepted standard on > layout and minimum required fields? > > If not, should there be? > > For example > > - Heading (short description) > - Description > - Inputs > - Input name + description > - Input type > - Outputs > - Output description > - Output type > > vs > > - Heading (short description) > - Inputs > - Input name + description > - Input type > - Outputs > - Output description > - Output type > - Description > > > I generally like the former, but given that the docstring in python follows > the function/method header rather than precedes it, it seems like the latter > would be better for python so that descriptions of the inputs and outputs > are not separated by lengthy descriptions. > > Comments/opinions?
In python-openstacksdk we go the route that has the description at the top, which is partially driven by our use of autodoc. It looks and reads better to describe what a method does and then show the options, versus giving a one sentence description, a bunch of detailed options, and then telling you a paragraph about what it can do. Even if you're not generating documentation out of it, having the in/out parameters as the last thing makes it a little more usable when reading the code itself. __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev