dotnet / dotnet/docs

Documentation for CSharpSyntaxWalker constructor needs clarification of "depth" parameter

Open
#33,866 0 comments 0 reactions 0 assignees View on GitHub
:watch: Not Triaged dotnet-roslyn-api/svc microsoft.codeanalysis/subsvc
Dominant language
No language data
Stars
4.8k
Forks
6.1k
Avg merge
19h 10m
Merged PRs (30d)
268

Description

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](https://github.com/dotnet/roslyn/issues/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.*

* ID: 7f4df4eb-e177-be67-06f2-6cd65d8cbac9
* Version Independent ID: 0b46d8cb-407a-94ed-a5a0-13528960b2a9
* Content: [CSharpSyntaxWalker Class (Microsoft.CodeAnalysis.CSharp)](https://learn.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.csharp.csharpsyntaxwalker?view=roslyn-dotnet-4.3.0)
* Content Source: [dotnet/xml/Microsoft.CodeAnalysis.CSharp/CSharpSyntaxWalker.xml](https://github.com/dotnet/roslyn-api-docs/blob/live/dotnet/xml/Microsoft.CodeAnalysis.CSharp/CSharpSyntaxWalker.xml)
* Product: **dotnet-roslyn-api**
* Technology: **microsoft.codeanalysis**
* GitHub Login: @dotnet-bot
* Microsoft Alias: **dotnetcontent**

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.