[Python-Dev] Questions/comments on documentation formatting (original) (raw)

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

-- Regards, Benjamin

More information about the Python-Dev mailing list