[Python-Dev] Questions/comments on documentation formatting

[Brett Cannon]

On Mon, Jan 19, 2009 at 19:19, Benjamin Peterson <benjamin at python.org> wrote:
> On Mon, Jan 19, 2009 at 9:11 PM, Brett Cannon <brett at python.org> wrote:
>> On Mon, Jan 19, 2009 at 19:01, Benjamin Peterson <benjamin at python.org> wrote:
>>> On Mon, Jan 19, 2009 at 8:24 PM, Brett Cannon <brett at python.org> wrote:
>>>>
>>>> 2. Should we start using function annotations?
>>>
>>> No, I think that information is better stored in the function description.
>>>
>>
>> Why? Putting it in the signature makes it very succinct and a simple
>> glance at the doc to see what type/ABC is expected.
>
> Well, I guess it's just not been explored. Feel free to try it out if
> you wish, though.
>

I just might.

>>
>>>>
>>>> 3. Are brackets for optional arguments (e.g. ``def fxn(a [, b=None [,
>>>> c=None]])``) really necessary when default argument values are
>>>> present? And do we really need to nest the brackets when it is obvious
>>>> that having on optional argument means the rest are optional as well?
>>>
>>> Actually, the defaults are usually documented in the description not
>>> the signature.
>>>
>>
>> OK, but that doesn't make it optimal. And that still doesn't answer my
>> question of whether all of those nested brackets are truly necessary.
>
> All I can say is that it is the style/convention.
>

Right, which is why I am questioning it. =)

>>
>>>>
>>>> 4. The var directive is not working even though the docs list it as a
>>>> valid directive; so is it still valid and something is broken, or the
>>>> docs need to be updated?
>>>
>>> The docs should be updated. "data" is the one to use now.
>>
>> So the 'data' directive turns into any variable, not just a module variables?
>
> "data" is for module level objects. If you're documenting properties
> or attributes in classes, use "attribute".

Then what are we supposed to use for arguments? Just ``literal``?

-Brett