Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Documentation for CSharpSyntaxWalker constructor needs clarification of "depth" parameter

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#33,866 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
68/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
csharp
Lĩnh vực
documentation

Hướng nghiên cứu

Bắt đầu với dotnet/xml/Microsoft.CodeAnalysis.CSharp/CSharpSyntaxWalker.xml, Content Source được nêu trong issue, và xem xét các mục về constructor, class và thuộc tính Depth của CSharpSyntaxWalker. Cập nhật tài liệu để giải thích hành vi mặc định của Depth, việc duyệt token và trivia, cũng như ý nghĩa của Depth; được xem là hoàn tất khi mỗi trang API được yêu cầu mô tả rõ ràng các hành vi này.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

: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.

Ngôn ngữ chính
Không có dữ liệu ngôn ngữ
Star
4.8k
Fork
6.1k
Merge trung bình
21 giờ 6 phút
Pull request đã merge (30 ngày)
193

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của dotnet/docs

Tất cả issue của dotnet/docs

Issue tương tự

Thêm issue về Documentation

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.