Open Stack

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?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150210/4cbe3e7f/attachment.html>