Miscellaneous improvements to the behavior and documentation of Visitor, Transformer, Interpreter, and friends

[nchammas]

This PR makes the following improvements.

Documentation:

• Add docstrings for visit_children_decor and various methods of Interpreter.
• Correct the top-level docs for Visitor to clarify that it can traverse the tree in either direction.
• Move utilities into their own section and add documentation for visit_children_decor, which was previously not visible.

Behavior:

• Have visit_children_decor raise a TypeError if applied to a method of any class other than Interpreter.

[erezsh]

visit_topdown would actually get the Interpreter to walk the tree bottom up

Can you explain this comment? Interpreter.top_down() would just use the __default__() method, no?

[nchammas]

Ah, I think I misinterpreted the behavior and jumped to the wrong conclusion.

Is the behavior of Interpreter.visit_topdown() fine as it is on master? Or is my proposed patch correct and just needs a fixed description?

[erezsh]

@nchammas Well, I can see how it was confusing. But I don't think adding visit_topdown fixes anything. Interpreter is behaving as expected, and if it's not implemented with the best design, that's another matter, but adding this method won't change that.

[erezsh]

Maybe it would be better to remove the __getattr__, but that would be slightly backwards-incompatible, in case anyone relied on this behavior, for some reason.

[nchammas]

@erezsh - No rush; just wanted to check in again if I can do anything to move this PR forward.

[nchammas]

Hi @erezsh - Is there anything I can do to move this PR forward, including reducing the scope? If not, happy to just close it.

[erezsh]

Hi @nchammas , sorry, I was a bit distracted with other projects. I'll try to allocate some time for Lark soon.

Do I have your permission to take the parts I like and leave out the rest? Some of the edits might remove the authorship marker from the commits, but I'll try to avoid it.

[nchammas]

Do I have your permission to take the parts I like and leave out the rest? Some of the edits might remove the authorship marker from the commits, but I'll try to avoid it.

Sure, go ahead. I have the "Allow edits by maintainers" thing enabled on this PR, so you can just push commits here if that's easiest for you.

[nchammas]

@erezsh - I've trimmed the nebulous changes to _visitor_args_dec from this PR. If there are any other changes I can make to get this merged, let me know. Otherwise, happy to close this.

[erezsh]

That looks good!

I rephrased one line. If you agree with it, then I think we're good to merge.

[nchammas]

LGTM!

[erezsh]

Thanks for improving the docs! Sorry it took me this long.

[nchammas]

No worries at all. Glad we got it merged.