Documentation of ast.walk misleadingly characterizes its behavior as recursive when it's really iterative

Documentation

Although the documentation claims that ast.walk generates nodes "in no specified order" and even describes its behavior as "Recursively yield all descendant nodes...", a look at the source code reveals that it really performs a breadth-first traversal by iteratively yielding child nodes in a queue:

def walk(node):
    """
    Recursively yield all descendant nodes in the tree starting at *node*
    (including *node* itself), in no specified order.  This is useful if you
    only want to modify nodes in place and don't care about the context.
    """
    from collections import deque
    todo = deque([node])
    while todo:
        node = todo.popleft()
        todo.extend(iter_child_nodes(node))
        yield node

I thought that maybe this function used to be recursive but found that it has not been modified since its first appearance in CPython 2.6.3.

I think we should at the minimum remove the wording "Recursively" from the description, and optionally:

1. Clarify the actual ordering by changing "in no specified order" to "in breadth-first order".
2. Add a keyword argument such as depth_first that defaults to False such that when it is true, switches to a depth-first traversal that behaves like:

def dfs_walk(node):
    yield node
    for child in ast.iter_child_nodes(node):
        yield from dfs_walk(child)

Bắt đầu với tài liệu về ast.walk được liên kết trong issue và so sánh cách diễn đạt của tài liệu đó với phần triển khai trong Lib/ast.py. Quyết định xem nên chỉ thực hiện thay đổi tối thiểu về cách diễn đạt hay cũng ghi lại thứ tự duyệt theo chiều rộng; tài liệu phải mô tả chính xác hành vi hiện có mà không thêm thay đổi API không được yêu cầu.