Open Stack

On Tue, Feb 10, 2015 at 1:57 PM, Min Pae <sputnik13 at 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.