[Python-Dev] Questions/comments on documentation formatting

[Benjamin Peterson]

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.

>
>>>
>>> 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.

>
>>>
>>> 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".



-- 
Regards,
Benjamin