Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Documentation for CSharpSyntaxWalker constructor needs clarification of "depth" parameter

Aperta Adatta ai principianti
  • Qualcosa non va?
#33,866 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
68/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Ferma
Stack tecnologico
csharp
Ambito
documentation

Direzione di ricerca

Inizia da dotnet/xml/Microsoft.CodeAnalysis.CSharp/CSharpSyntaxWalker.xml, il Content Source indicato nell’issue, e rivedi le voci del costruttore, della classe e della proprietà Depth di CSharpSyntaxWalker. Aggiorna la documentazione per spiegare il comportamento predefinito di Depth, la visita di token e trivia e il significato di Depth; il lavoro è completo quando ogni pagina API richiesta descrive chiaramente questi comportamenti.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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

Lingua principale
Nessun dato sulla lingua
Stelle
4.8k
Fork
6.1k
Merge medio
14h 40m
PR unite (30g)
302

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di dotnet/docs

Tutte le issue di dotnet/docs

Issue simili

Altre issue su Documentation

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.