Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Documentation for CSharpSyntaxWalker constructor needs clarification of "depth" parameter

Open Beginner friendly
  • Is something wrong?
#33,866 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
68/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Stale
Tech stack
csharp
Domain
documentation

Research direction

Start with dotnet/xml/Microsoft.CodeAnalysis.CSharp/CSharpSyntaxWalker.xml, the Content Source named in the issue, and review the CSharpSyntaxWalker constructor, class, and Depth property entries. Update the documentation to explain the default depth behavior, token and trivia visitation, and the meaning of Depth; done means each requested API page clearly describes these behaviors.

Written by the indexing model from the issue text.

Description

:watch: Not Triaged dotnet-roslyn-api/svc microsoft.codeanalysis/subsvc

Currently, in a derived syntax walker without an explicit constructor, the syntax walker will not visit tokens or trivia nodes. This is extremely non-obvious.

I wasted about half a day discovering this behavior, confirming it, opening an issue, discovering the underlying cause, and then closing the issue (see #66713).

The documentation desperately needs improvements in this regard.

First, the Constructor page should better explain both the usage and the default value of the terribly named depth parameter. Currently, it lists only the name and data type of the parameter and no additional information. I suggest adding something like the following:

The value of this parameter limits the types of nodes that will be visited. With its default value of SyntaxWalkerDepth.Node, neither tokens nor trivia are visited.

Next, the Class page should warn that by default this class will not visit tokens or trivia nodes. I suggest adding something like the following:

By default, this class will not visit tokens or trivia. To change this behavior, supply a different value for the depth parameter of the constructor.

Next, on the same page, the documentation for the Depth property should be improved. Currently, it only provides the property name and no further information. I suggest adding something like the following:

Gets a value that indicates the types of nodes that will be visited.

Finally, on the Property page for Depth, a similar description should be added. Currently, it only provides the name and data type and no further information.

Regarding the poor naming of the parameter and property, the word "depth" generally has a different meaning when referring to a tree data structure. There, it is a measure of the distance between a given node and the root of the tree.

In this class, the name depth refers to a filter that limits the types of nodes that will be visited. While this loosely relates to the previously mentioned concept of "depth", since descent stops at the depth where a node does not match the filter, it is nonetheless poorly named.

Better names include: "depthLimit", "depthFilter", "filter", "limit", and frankly almost anything else 😄

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

Dominant language
No language data
Stars
4.8k
Forks
6.1k
Avg merge
14h 40m
Merged PRs (30d)
302

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from dotnet/docs

All issues in dotnet/docs

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.