add documentation for overlay annotations #21184
Conversation
ginsbach
force-pushed
the
ginsbach/OverlayDocumentation
branch
3 times, most recently
from
5edf815 to
ef4eb11
Compare
ginsbach
force-pushed
the
ginsbach/OverlayDocumentation
branch
from
ef4eb11 to
4e478c3
Compare
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for overlay annotations, a feature that enables efficient incremental analysis in CodeQL. The documentation explains six overlay annotations that control how predicates behave during overlay evaluation, helping developers understand and resolve compilation errors when overlay support is enabled.
Changes:
- Added new "Overlay annotations" section to annotations.rst with detailed descriptions, examples, and troubleshooting guidance for all six overlay annotation types
- Updated ql-language-specification.rst to include overlay annotations in the grammar and applicability table
- Enhanced the QL lexer to properly highlight overlay annotation syntax
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/codeql/qllexer.py | Updated regex pattern to recognize overlay annotations with optional ? suffix for syntax highlighting |
| docs/codeql/ql-language-reference/ql-language-specification.rst | Added overlay to argsAnnotation grammar and created applicability table showing which language constructs support each overlay annotation variant |
| docs/codeql/ql-language-reference/annotations.rst | Added comprehensive overlay annotations section documenting all six annotation types (local, local?, global, caller, caller?, discard_entity) with descriptions, use cases, code examples, inheritance behavior, and error resolution guidance |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| predicates are evaluated separately on base and overlay data, with results combined at | ||
| the frontier between local and global code. Global predicates operate on the combined | ||
| data. Local predicates typically take time proportional to the diff size, while global | ||
| predicates take time proportional to the full codebase. |
There was a problem hiding this comment.
I would still include When a global predicate calls a local predicate, results from both the base and overlay evaluations are combined, with stale base results filtered out through a process called "discarding.", since otherwise it's not clear where discard predicates fit in. In that case, maybe drop , with results combined at the frontier between local and global code.
So maybe something like To achieve this, predicates are divided into *local* and *global* categories, with global being the default. Local predicates are evaluated independently on base and overlay data, and thus typically take time proportional to the diff size; global predicates operate on the combined data, and thus take time proportional to the full codebase. When a global predicate calls a local predicate, results from both the base and overlay evaluations of the local predicate are combined, with stale base results filtered out through a process called "discarding.".
| from the base database as possible. Ideally, analysis time is proportional to the size | ||
| of the diff rather than the full codebase. | ||
|
|
||
| To achieve this, predicates are divided into *local* and *global* categories. Local |
There was a problem hiding this comment.
Maybe add , with global being the default.
| of the diff rather than the full codebase. | ||
|
|
||
| To achieve this, predicates are divided into *local* and *global* categories. Local | ||
| predicates are evaluated separately on base and overlay data, with results combined at |
There was a problem hiding this comment.
Maybe independently instead of separately.
Adds public-facing documentation for overlay annotations to the QL language reference and specification. These annotations control predicate behavior during overlay evaluation, a feature for incremental analysis used primarily by GitHub Code Scanning for pull request analysis.
Changes
overlay[local],overlay[local?],overlay[global],overlay[caller],overlay[caller?],overlay[discard_entity]) with descriptions, examples, and troubleshooting for common compilation errorsMotivation
When overlay compilation is enabled for a QL pack, developers may encounter compilation errors related to overlay constraints. This documentation helps QL developers understand what the annotations mean and resolve errors in custom libraries.