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?

All the examples in triple backticks are place in source files for QL tests. That way we can test that the examples in the docs are actually valid. The "not yet implemented" stuff comes from the expansion of the todo!() macro.

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.

They were co-piliot's idea, and I quite like them too. Ideally we make those ^^ things inline expectation markers, so we get even stronger testing of the documentation examples. @redsun82 perhaps something for a rainy afternoon ;-)

Perhaps copilot was inspired by the excellent comments in https://github.com/github/codeql/blob/main/shared/typeinference/codeql/typeinference/internal/TypeInference.qll ;-)

rust/schema/annotations.py

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

I dropped the acronym, actually not much point defining a fancy acronym if it is not used anywhere in the text

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!

geoffw0 · 2025-06-04T10:37:23Z

My comments have all been addressed and I'm [very] happy with the PR. @redsun82 please approve if you're happy your comments have been addressed as well.

redsun82

thanks a lot!

github-actions bot added the Rust Pull requests that update Rust code 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 previously approved these changes Jun 3, 2025

View reviewed changes

aibaars dismissed redsun82’s stale review via 58b0e41 June 4, 2025 09:13

aibaars added 3 commits June 4, 2025 15:38

Rust: address comments

7a13c98

Rust: run codegen

e878782

Rust: update expected output

39851bc

aibaars force-pushed the aibaars/qldoc-ast branch from 58b0e41 to 39851bc Compare June 4, 2025 13:45

redsun82 approved these changes Jun 4, 2025

View reviewed changes

aibaars merged commit 189c16b into main Jun 4, 2025
15 of 16 checks passed

aibaars deleted the aibaars/qldoc-ast branch June 4, 2025 14:04

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

Rust: add documentation for AST nodes #19630

Rust: add documentation for AST nodes #19630

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

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!

redsun82 left a comment

Choose a reason for hiding this comment

Uh oh!

geoffw0 commented Jun 4, 2025

Uh oh!

redsun82 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

aibaars commented May 30, 2025 •

edited

Loading