Rust: add documentation for AST nodes #19630

aibaars · 2025-05-30T08:56:12Z

This pull request adds missing documentation for Rust AST nodes. Best reviewed commit-by-commit, skipping the codegen ones. The most important changed files is rust/schema/annotations.py where the missing documentation was added.

Copilot

Pull Request Overview

This PR adds detailed documentation comments for various Rust AST node classes and updates the .gitattributes to include generated test files that were previously marked as missing.

Enriches QLL class docs with clear descriptions and examples for associated items, inline assembly elements, array types, argument lists, and ABI specs.
Introduces a constructor predicate in ControlFlowGraphImpl.qll to filter out macro pattern calls.
Replaces MISSING_SOURCE.txt entries in .gitattributes with actual .ql test paths for inline assembly and other elements.

Reviewed Changes

Copilot reviewed 644 out of 644 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
rust/ql/lib/codeql/rust/elements/AssocTypeArg.qll	Added a descriptive doc comment and example for associated type arguments.
rust/ql/lib/codeql/rust/elements/AssocItemList.qll	Extended doc to mention `Impl` contexts; refined formatting.
rust/ql/lib/codeql/rust/elements/AssocItem.qll	Updated comment to describe associated items in traits/impls with example.
rust/ql/lib/codeql/rust/elements/Asm*.qll	Added docs and examples for inline assembly symbols, registers, options, etc.
rust/ql/lib/codeql/rust/elements/ArrayTypeRepr.qll	Documented array type representations with example.
rust/ql/lib/codeql/rust/elements/ArgList.qll	Clarified argument list usage in calls with example.
rust/ql/lib/codeql/rust/elements/Abi.qll	Documented ABI specs for extern functions/blocks.
rust/ql/lib/codeql/rust/controlflow/internal/ControlFlowGraphImpl.qll	Added `MacroCallTree()` predicate to exclude calls in macro patterns.
rust/ql/.gitattributes	Replaced missing-source placeholders with actual generated `.ql` test entries.

rust/ql/lib/codeql/rust/elements/AssocItemList.qll

geoffw0 · 2025-06-03T10:18:11Z

rust/ql/test/library-tests/controlflow/CONSISTENCY/CfgConsistency.expected

-| test.rs:455:13:455:25 | [match(false)] 1 \| 2 | no-match | test.rs:455:13:455:25 | one_or_two!... |
-| test.rs:455:13:455:25 | [match(false)] 1 \| 2 | no-match | test.rs:456:13:456:13 | _ |
-| test.rs:455:13:455:25 | [match(true)] 1 \| 2 | match | test.rs:455:13:455:25 | one_or_two!... |
-| test.rs:455:13:455:25 | [match(true)] 1 \| 2 | match | test.rs:455:30:455:30 | 3 |


geoffw0 · 2025-06-03T10:25:15Z

rust/schema/annotations.py

-    Foo<'a>
-    //  ^^
+    let text: Text<'a>;
+    //             ^^


Improvements to examples 👍.

geoffw0 · 2025-06-03T10:28:22Z

rust/ql/test/extractor-tests/generated/ArgList/ArgList_getArg.expected

-| gen_arg_list.rs:5:5:5:11 | ArgList | 0 | gen_arg_list.rs:5:5:5:11 | "not yet implemented" |
+| gen_arg_list.rs:7:8:7:16 | ArgList | 0 | gen_arg_list.rs:7:9:7:9 | 1 |
+| gen_arg_list.rs:7:8:7:16 | ArgList | 1 | gen_arg_list.rs:7:12:7:12 | 2 |
+| gen_arg_list.rs:7:8:7:16 | ArgList | 2 | gen_arg_list.rs:7:15:7:15 | 3 |


Why are we getting better test results from doc changes? Are these the tests of the example code you were talking about earlier today?

geoffw0 · 2025-06-03T10:29:50Z

rust/schema/annotations.py

    ```rust
-    todo!()
+    extern "C" fn foo() {}
+    //     ^^^


New documentation 👍 (I won't claim to have picked through it with a fine-toothed comb, but it all looks good at a glance, and is certainly an improvement on all those todo!()s).

geoffw0 · 2025-06-03T10:33:19Z

rust/schema/annotations.py

    ```rust
-    todo!()
+    fn foo<T, U>(t: T, u: U) {}
+    //     ^  ^


The ^ are a helpful addition in many of these examples.

geoffw0 · 2025-06-03T10:40:34Z

rust/schema/annotations.py

+    (x + y)
+    //^^^^^


Suggested change

(x + y)

//^^^^^

(x + y)

//^^^^^^^

geoffw0 · 2025-06-03T10:40:53Z

rust/schema/annotations.py

+    pub struct S;
+    //^^^


Suggested change

pub struct S;

//^^^

pub struct S;

//^^^

geoffw0 · 2025-06-03T10:48:52Z

rust/schema/annotations.py

    ```
    """


 @annotate(UseTree)
 class _:
    """
-    A UseTree. For example:
+    A `use` tree, ie the part after the `use` keyword in a `use` statement. For example:


Suggested change

A `use` tree, ie the part after the `use` keyword in a `use` statement. For example:

A `use` tree, that is, the part after the `use` keyword in a `use` statement. For example:

We're supposed to prefer "that is" to "ie" in documentation.

geoffw0 · 2025-06-03T10:50:05Z

rust/schema/annotations.py

+    x: i32,
+        y: i32,


Suggested change

x: i32,

y: i32,

x: i32,

y: i32,

geoffw0 · 2025-06-03T10:51:41Z

rust/schema/annotations.py

+    use std::{fs, io};
+    //        ^^^^^^^


Suggested change

use std::{fs, io};

// ^^^^^^^

use std::{fs, io};

// ^^^^^^^^

I'm not sure if this range should include both {} or neither, but it surely should not include one but not the other. (nit)

redsun82 · 2025-06-03T11:39:54Z

rust/schema/annotations.py

@@ -1069,9 +1142,17 @@ class _:
 @annotate(ForTypeRepr)
 class _:
    """
-    A ForTypeRepr. For example:
+    A higher-ranked trait bound(HRTB) type.


Suggested change

A higher-ranked trait bound(HRTB) type.

A higher-ranked trait bound (HRTB).

redsun82 · 2025-06-03T11:47:42Z

rust/schema/annotations.py

+    println!("{} {}!", "Hello", "world");
+    //      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    ```
+    ```


Suggested change

```

```rust

redsun82

LGTM, that's a very good improvement in both documentation and testing 👍

Some minor cosmetic nits, but this is really neat!

github-actions bot added the Rust label May 30, 2025

aibaars force-pushed the aibaars/qldoc-ast branch from 353c39f to 628a741 Compare May 30, 2025 09:41

aibaars added 4 commits May 30, 2025 11:46

Rust: add documentation for AST nodes

460984b

Rust: add missing AST nodes to annotations.py

0dd0f9a

Rust: run codegen

f0db47b

Rust: delete empty expected file

0157c16

aibaars force-pushed the aibaars/qldoc-ast branch from 628a741 to 858e372 Compare May 30, 2025 16:58

aibaars added 3 commits May 30, 2025 22:55

Rust: fix QLdoc examples

0c8e886

Rust: codegen

c44a7c3

update output

943dd8e

aibaars force-pushed the aibaars/qldoc-ast branch from 858e372 to 943dd8e Compare May 30, 2025 21:00

Rust: fix CFG for MacroPat

ae0c547

aibaars force-pushed the aibaars/qldoc-ast branch from 883aa89 to ae0c547 Compare June 2, 2025 14:38

aibaars marked this pull request as ready for review June 2, 2025 15:06

Copilot AI review requested due to automatic review settings June 2, 2025 15:06

aibaars requested a review from a team as a code owner June 2, 2025 15:06

Copilot AI reviewed Jun 2, 2025

View reviewed changes

rust/ql/lib/codeql/rust/elements/AssocItemList.qll Outdated Show resolved Hide resolved

Rust: remove stray space

348dc99

geoffw0 reviewed Jun 3, 2025

View reviewed changes

redsun82 reviewed Jun 3, 2025

View reviewed changes

redsun82 approved these changes Jun 3, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Rust: add documentation for AST nodes #19630

Rust: add documentation for AST nodes #19630

aibaars commented May 30, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

geoffw0 Jun 3, 2025

Uh oh!

geoffw0 Jun 3, 2025

Uh oh!

geoffw0 Jun 3, 2025

Uh oh!

geoffw0 Jun 3, 2025

Uh oh!

geoffw0 Jun 3, 2025

Uh oh!

geoffw0 Jun 3, 2025

Uh oh!

geoffw0 Jun 3, 2025

Uh oh!

geoffw0 Jun 3, 2025

Uh oh!

geoffw0 Jun 3, 2025

Uh oh!

geoffw0 Jun 3, 2025

Uh oh!

redsun82 Jun 3, 2025

Uh oh!

redsun82 Jun 3, 2025

Uh oh!

redsun82 left a comment

Uh oh!

Uh oh!

-    (x + y)
-    //^^^^^
+      (x + y)
+    //^^^^^^^

	A `use` tree, ie the part after the `use` keyword in a `use` statement. For example:
	A `use` tree, that is, the part after the `use` keyword in a `use` statement. For example:

-    x: i32,
-        y: i32,
+        x: i32,
+        y: i32,

	A higher-ranked trait bound(HRTB) type.
	A higher-ranked trait bound (HRTB).

Rust: add documentation for AST nodes #19630

Are you sure you want to change the base?

Rust: add documentation for AST nodes #19630

Conversation

aibaars commented May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

redsun82 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aibaars commented May 30, 2025 •

edited

Loading