[Python-Dev] Questions/comments on documentation formatting
benjamin at python.org
Tue Jan 20 15:26:38 CET 2009
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*.
More information about the Python-Dev