[Python-Dev] Questions/comments on documentation formatting

[Benjamin Peterson]

On Mon, Jan 19, 2009 at 11:56 PM, Brett Cannon <brett at python.org> wrote:
> 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.


We might be opening a can of worms, though. Do we document everything
that takes a dictionary argument with collections.Mapping or
everything that takes a integer numbers.Rationale? What if multiple
types are possible?

>>>>> 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``?

No, use *some_argument*.



-- 
Regards,
Benjamin