Recurse into special constructs to find document symbols

[lionel-]

Addresses posit-dev/positron#8881

We now consistently recurse inside these constructs to collect nested document symbols such as comment sections:

• if-else branches
• loops

The behaviour regarding nested assignments implemented in #859 has been adapted so that { blocks in if-else branches and loops still counts as top-level. This way these assignments are all treated as consistently part of the outline:

x <- 1

if (TRUE) {
  x <- 2
} else {
  x <- 3
}

for (i in xs) {
  x <- 4
}

In addition we also now collect comment sections in parameter lists of function definitions:

x <- function(
  # section ----
  arg
) {
  ...
}

QA Notes

Comment sections and other kinds of document symbols in if-else branches and loops are now part of the outline:

# top ----

if (TRUE) {
  # if ----
  foo <- function() {}
} else {
  # else ----
  foo <- function() {}
}

for (i in xs) {
  # loop ----
  bar <- function() {}
}

Comment sections in parameter lists of function definitions are now included as well. We don't recurse through default arguments though.

x <- function(
  # section ----
  arg = function() {
    # not a section ----
  }
) {
  ...
}

[DavisVaughan]

A few questions requesting clarifying behavior and a few more tests but I think this looks fairly straightforward?

[DavisVaughan]

Does this change the behavior of general braced expressions? i.e.

# a section ----

{
  # another one ----
}

And do we have tests for this?

[lionel-]

Good point! We tested the brace-in-call and brace-in-function cases, but not the brace-in-program case.

I've tweaked a snapshot to include these (as well as the brace-in-brace case) and regenerated before all changes in this PR, then reran the tests with all the changes (including removed current_level), and there were no snapshot changes.

[DavisVaughan]

I'm not sure what this comment means. Does it mean no recursion? Can you provide more details?

[lionel-]

yep no recursion, the comment is now clearer about that

[DavisVaughan]

Hmmmmmm 0? Are you sure you shouldn't pass the current_level through to here? You do for the function body. Add a test either way about this behavior?

[DavisVaughan]

Or at least a comment here about why its 0

[lionel-]

I meant 0 here, but I think you're right to be confused. With the changes made over time, we no longer propagate the current level across syntax constructs. So I've just removed this argument.