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.
| Annotation inheritance | ||
| ---------------------- | ||
|
|
||
| Overlay annotations can be applied to modules and types, in which case they are |
There was a problem hiding this comment.
The description states that overlay annotations can be applied to "Classes | Characters" but characters (characteristic predicates) are not mentioned in the code examples or detailed descriptions above. The specification table shows they apply to characters, but the detailed section only mentions "modules and types". Consider clarifying whether "types" includes characteristic predicates, or explicitly mention characteristic predicates in the description text on line 640.
| Overlay annotations can be applied to modules and types, in which case they are | |
| Overlay annotations can be applied to modules, types, and characteristic predicates (characters), in which case they are |
There was a problem hiding this comment.
@copilot I'm trying to make a point here that overlay annotations on modules and types also apply to nested declarations. Characteristic predicates (or any other predicates, really) cannot have relevant nested declarations. Feel free to come up with another suggestion that takes this into account, but I don't want to commit your suggestion above.
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.