ast - docs for every node type are missing

[techtonik]

BPO	19557
Nosy	@birkenfeld, @ezio-melotti, @csabella, @pablogsal, @isidentical
Superseder	bpo-39199: Improve the AST documentation

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-01-12.14:30:47.314>
created_at = <Date 2013-11-12.06:52:24.605>
labels = ['docs']
title = 'ast - docs for every node type are missing'
updated_at = <Date 2020-01-12.14:30:47.310>
user = 'https://bugs.python.org/techtonik'

bugs.python.org fields:

activity = <Date 2020-01-12.14:30:47.310>
actor = 'cheryl.sabella'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-01-12.14:30:47.314>
closer = 'cheryl.sabella'
components = ['Documentation']
creation = <Date 2013-11-12.06:52:24.605>
creator = 'techtonik'
dependencies = []
files = []
hgrepos = []
issue_num = 19557
keywords = []
message_count = 10.0
messages = ['202675', '202697', '203734', '204073', '204479', '204513', '204528', '204529', '359759', '359851']
nosy_count = 7.0
nosy_names = ['georg.brandl', 'techtonik', 'ezio.melotti', 'docs@python', 'cheryl.sabella', 'pablogsal', 'BTaskaya']
pr_nums = []
priority = 'low'
resolution = 'duplicate'
stage = 'resolved'
status = 'closed'
superseder = '39199'
type = None
url = 'https://bugs.python.org/issue19557'
versions = []

[techtonik]

http://docs.python.org/2/library/ast.html

AST module doc is incomplete. To write node visitor, you need to know possible types of parameters and expected values for every node type. They are different.

http://hg.python.org/cpython/file/1ee45eb6aab9/Parser/Python.asdl

For example, visit_Assign expects:
Assign(targets, value)
targets can be List, Tuple or Name

When there is List, and when there is Tuple? It should be documented.

[brettcannon]

The node types are all listed right there in the docs in the abstract grammar section, so arguing they are incomplete I don't think is accurate.

I'm willing to leave this open in case some ambitious person wants to write docs for every node type, but I think this is a very low priority task.

[techtonik]

Neither you nor docs answer the question when Assign node gets Tuple as argument, when List and when Subscript.

While it is obvious to you, I personally don't know what a Subscript is. This is the kind of stuff that I'd like to see documented.

[techtonik]

http://stackoverflow.com/questions/8370132/what-syntax-is-represented-by-an-extslice-node-in-pythons-ast

[techtonik]

https://greentreesnakes.readthedocs.org/en/latest/

[birkenfeld]

When citing a link, it's customary to give at least a comment *why* you are citing it.

[techtonik]

SO link serves a proof that a problem is actual. It is needed, because, for example Brett doesn't think it is important.

2nd link is the same proof, and also an example of documentation wanted.

[techtonik]

In fact it may be the documentation that could be merged.

[isidentical]

@pablogsal is working on documenting nodes (not every node type that exists, the ones that aren't deprecated) in PR 17812

[csabella]

@BTaskaya, thank you. I'm going to close this issue as a duplicate of that one.