Document ordering of SyntaxNode Ancestor methods

[Copilot]

The XML documentation for Ancestors(), AncestorsAndSelf(), and FirstAncestorOrSelf() methods did not specify the traversal order, while similar methods like DescendantNodes() explicitly document ordering as "in prefix document order."

Changes

Updated XML documentation for four public methods in SyntaxNode:

• Ancestors(): Returns "ancestor nodes in order from the innermost containing syntactic ancestor to the outermost"
• AncestorsAndSelf(): Returns "ancestor nodes (including this node) in order from this node to the outermost ancestor"
• FirstAncestorOrSelf<TNode>(): Clarifies "ancestors are searched in order from this node to the outermost ancestor"
• FirstAncestorOrSelf<TNode, TArg>(): Same clarification as above

Example

var expr = SyntaxFactory.ParseExpression("a + (b - (c * (d / e)))");
var e = expr.DescendantNodes().OfType<IdentifierNameSyntax>().First(n => n.Identifier.Text == "e");

var ancestors = e.Ancestors().ToList();
// ancestors[0] is DivideExpression (immediate parent)
// ancestors[1] is ParenthesizedExpression
// ancestors[2] is MultiplyExpression
// ...
// ancestors[6] is AddExpression (root)

This ordering allows reliable use of LINQ methods like .First() to get the immediate parent or closest matching ancestor.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• kijvsblobprodcus387.vsblob.vsassets.io
  • Triggering command: /usr/share/dotnet/dotnet dotnet build src/Compilers/Core/Portable/Microsoft.CodeAnalysis.csproj --no-incremental /home/REDACTED/work/roslyn/roslyn/src/ExpressionEvaluator/Core/Test/ResultProvider/Debugger/Engine/DkmSuccessEvaluationResult.cs /home/REDACTED/work/roslyn/roslyn/src/ExpressionEvaluator/Core/Test/ResultProvider/Debugger/Engine/DkmCompilerId.cs /home/REDACTED/work/roslyn/roslyn/src/ExpressionEvaluator/Core/Test/ResultProvider/Debugger/Engine/DkmClrAppDomain.cs /home/REDACTED/work/roslyn/roslyn/src/ExpressionEvaluator/Core/Test/ResultProvider/Debugger/Engine/IDkmClrFormatter.cs /home/REDACTED/work/roslyn/roslyn/src/ExpressionEvaluator/Core/Test/ResultProvider/Debugger/Engine/DkmEvaluationResultFlags.cs /home/REDACTED/work/roslyn/roslyn/src/ExpressionEvaluator/Core/Test/ResultProvider/Deb�� /home/REDACTED/work/roslyn/roslyn/src/ExpressionEvaluator/Core/Test/ResultProvider/Debugger/Engine/DkmDataItem.cs /home/REDACTED/work/roslyn/roslyn/src/ExpressionEvaluator/Core/Test/ResultProvider/Debugger/Engine/DkmEvaluationFlags.cs (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>SyntaxNode.Ancestors() does not specify order of returned list</issue_title>
<issue_description>### Type of issue

Missing information

Description

The documentation for SyntaxNode.Ancestors() and .AncestorsAndSelf() does not specify the order of the nodes in the returned list. Knowing the order is important because it affects whether we can use LINQ selectors like .First() on the result and get what we expect.

By comparison, other docs pages (like ChildNodes, DescendantNodes, etc) do mention the ordering.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.syntaxnode.ancestors?view=roslyn-dotnet-5.0.0&viewFallbackFrom=net-8.0

Content source URL

https://github.com/dotnet/roslyn-api-docs/blob/live/dotnet/xml/Microsoft.CodeAnalysis/SyntaxNode.xml</issue_description>

<agent_instructions>@copilot Look for as many public 'AncestorXXX' methods you can find in the syntax model and document them. This is at least 'Ancestors' and 'AncestorsAndSelf'.

This should document that this returns ancestors from innermost containing syntactic ancestor to outermost. </agent_instructions>

Comments on the Issue (you are @copilot in this section)

@jjonescz If the docs don't mention ordering, that likely means the order is not guaranteed. Might need API review to change that.

• Fixes SyntaxNode.Ancestors() does not specify order of returned list #81797

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[CyrusNajmabadi]

@dotnet/roslyn-compiler for more eyes.

[jcouv]

for more eyes.

FYI, the PR is in Draft state and doesn't have any labels

[jcouv]

LGTM Thanks (commit 2)

[jcouv]

Can be merged with a single review single doc-only change. Thanks

[CyrusNajmabadi]

Can be merged with a single review single doc-only change. Thanks

Good to know. Thanks!