Skip to content

Commit cca05e0

Browse files
AlexDenisovAlexDenisov
authored
Merge pull request #14902 from github/redsun82/swift-qldocs
Codegen: allow marking properties as internal
2 parents b514bd8 + ba098c3 commit cca05e0

File tree

12 files changed

+81
-54
lines changed

12 files changed

+81
-54
lines changed

‎misc/codegen/generators/qlgen.py

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,7 @@ def get_ql_property(cls: schema.Class, prop: schema.Property, lookup: typing.Dic
114114
description=prop.description,
115115
synth=bool(cls.synth) or prop.synth,
116116
type_is_hideable=lookup[prop.type].hideable if prop.type in lookup else False,
117+
internal="ql_internal" in prop.pragmas,
117118
)
118119
if prop.is_single:
119120
args.update(
@@ -151,7 +152,7 @@ def get_ql_property(cls: schema.Class, prop: schema.Property, lookup: typing.Dic
151152

152153

153154
def get_ql_class(cls: schema.Class, lookup: typing.Dict[str, schema.Class]) -> ql.Class:
154-
pragmas = {k: True for k in cls.pragmas if k.startswith("ql")}
155+
pragmas = {k: True for k in cls.pragmas if k.startswith("qltest")}
155156
prev_child = ""
156157
properties = []
157158
for p in cls.properties:
@@ -167,6 +168,7 @@ def get_ql_class(cls: schema.Class, lookup: typing.Dict[str, schema.Class]) -> q
167168
dir=pathlib.Path(cls.group or ""),
168169
doc=cls.doc,
169170
hideable=cls.hideable,
171+
internal="ql_internal" in cls.pragmas,
170172
**pragmas,
171173
)
172174

@@ -313,7 +315,7 @@ def _get_stub(cls: schema.Class, base_import: str, generated_import_prefix: str)
313315
accessors = []
314316
return ql.Stub(name=cls.name, base_import=base_import, import_prefix=generated_import_prefix,
315317
doc=cls.doc, synth_accessors=accessors,
316-
ql_internal="ql_internal" in cls.pragmas)
318+
internal="ql_internal" in cls.pragmas)
317319

318320

319321
_stub_qldoc_header = "// the following QLdoc is generated: if you need to edit it, do it in the schema file\n"
@@ -397,15 +399,15 @@ def generate(opts, renderer):
397399
_patch_class_qldoc(c.name, qldoc, stub_file)
398400

399401
# for example path/to/elements -> path/to/elements.qll
400-
renderer.render(ql.ImportList([i for name, i in imports.items() if not classes[name].ql_internal]),
402+
renderer.render(ql.ImportList([i for name, i in imports.items() if not classes[name].internal]),
401403
include_file)
402404

403405
elements_module = get_import(include_file, opts.root_dir)
404406

405407
renderer.render(
406408
ql.GetParentImplementation(
407409
classes=list(classes.values()),
408-
imports=[elements_module] + [i for name, i in imports.items() if classes[name].ql_internal],
410+
imports=[elements_module] + [i for name, i in imports.items() if classes[name].internal],
409411
),
410412
out / 'ParentChild.qll')
411413

‎misc/codegen/lib/ql.py

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ class Property:
4444
doc_plural: Optional[str] = None
4545
synth: bool = False
4646
type_is_hideable: bool = False
47+
internal: bool = False
4748

4849
def __post_init__(self):
4950
if self.tableparams:
@@ -80,10 +81,6 @@ def is_single(self):
8081
def is_child(self):
8182
return self.prev_child is not None
8283

83-
@property
84-
def has_description(self) -> bool:
85-
return bool(self.description)
86-
8784
@property
8885
def is_indexed(self) -> bool:
8986
return self.is_repeated and not self.is_unordered
@@ -112,7 +109,7 @@ class Class:
112109
qltest_skip: bool = False
113110
qltest_collapse_hierarchy: bool = False
114111
qltest_uncollapse_hierarchy: bool = False
115-
ql_internal: bool = False
112+
internal: bool = False
116113
doc: List[str] = field(default_factory=list)
117114
hideable: bool = False
118115

@@ -162,7 +159,7 @@ class Stub:
162159
base_import: str
163160
import_prefix: str
164161
synth_accessors: List[SynthUnderlyingAccessor] = field(default_factory=list)
165-
ql_internal: bool = False
162+
internal: bool = False
166163
doc: List[str] = field(default_factory=list)
167164

168165
@property
@@ -171,7 +168,7 @@ def has_synth_accessors(self) -> bool:
171168

172169
@property
173170
def has_qldoc(self) -> bool:
174-
return bool(self.doc) or self.ql_internal
171+
return bool(self.doc) or self.internal
175172

176173

177174
@dataclass

‎misc/codegen/templates/ql_class.mustache

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,9 @@ module Generated {
7171
* {{>ql_property_doc}} *
7272
* This includes nodes from the "hidden" AST. It can be overridden in subclasses to change the
7373
* behavior of both the `Immediate` and non-`Immediate` versions.
74+
{{#internal}}
75+
* INTERNAL: Do not use.
76+
{{/internal}}
7477
*/
7578
{{type}} get{{#is_unordered}}An{{/is_unordered}}Immediate{{singular}}({{#is_indexed}}int index{{/is_indexed}}) {
7679
{{^synth}}
@@ -83,11 +86,12 @@ module Generated {
8386

8487
/**
8588
* {{>ql_property_doc}} *
86-
{{#has_description}}
8789
{{#description}}
8890
* {{.}}
8991
{{/description}}
90-
{{/has_description}}
92+
{{#internal}}
93+
* INTERNAL: Do not use.
94+
{{/internal}}
9195
*/
9296
final {{type}} {{getter}}({{#is_indexed}}int index{{/is_indexed}}) {
9397
exists({{type}} immediate | immediate = this.get{{#is_unordered}}An{{/is_unordered}}Immediate{{singular}}({{#is_indexed}}index{{/is_indexed}}) and
@@ -98,11 +102,12 @@ module Generated {
98102
{{^type_is_hideable}}
99103
/**
100104
* {{>ql_property_doc}} *
101-
{{#has_description}}
102105
{{#description}}
103106
* {{.}}
104107
{{/description}}
105-
{{/has_description}}
108+
{{#internal}}
109+
* INTERNAL: Do not use.
110+
{{/internal}}
106111
*/
107112
{{type}} {{getter}}({{#is_indexed}}int index{{/is_indexed}}) {
108113
{{^synth}}
@@ -117,6 +122,9 @@ module Generated {
117122
{{#is_optional}}
118123
/**
119124
* Holds if `{{getter}}({{#is_repeated}}index{{/is_repeated}})` exists.
125+
{{#internal}}
126+
* INTERNAL: Do not use.
127+
{{/internal}}
120128
*/
121129
final predicate has{{singular}}({{#is_repeated}}int index{{/is_repeated}}) {
122130
exists(this.{{getter}}({{#is_repeated}}index{{/is_repeated}}))
@@ -126,6 +134,9 @@ module Generated {
126134

127135
/**
128136
* Gets any of the {{doc_plural}}.
137+
{{#internal}}
138+
* INTERNAL: Do not use.
139+
{{/internal}}
129140
*/
130141
final {{type}} {{indefinite_getter}}() {
131142
result = this.{{getter}}(_)
@@ -134,6 +145,9 @@ module Generated {
134145

135146
/**
136147
* Gets the number of {{doc_plural}}.
148+
{{#internal}}
149+
* INTERNAL: Do not use.
150+
{{/internal}}
137151
*/
138152
final int getNumberOf{{plural}}() {
139153
result = count(int i | exists(this.{{getter}}(i)))
@@ -143,6 +157,9 @@ module Generated {
143157
{{#is_unordered}}
144158
/**
145159
* Gets the number of {{doc_plural}}.
160+
{{#internal}}
161+
* INTERNAL: Do not use.
162+
{{/internal}}
146163
*/
147164
final int getNumberOf{{plural}}() {
148165
result = count(this.{{getter}}())

‎misc/codegen/templates/ql_db.mustache

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,9 @@ module Raw {
1818
{{^synth}}
1919
/**
2020
* {{>ql_property_doc}} *
21-
{{#has_description}}
2221
{{#description}}
2322
* {{.}}
2423
{{/description}}
25-
{{/has_description}}
2624
*/
2725
{{type}} {{getter}}({{#is_indexed}}int index{{/is_indexed}}) {
2826
{{tablename}}({{#tableparams}}{{^first}}, {{/first}}{{param}}{{/tableparams}})

‎misc/codegen/templates/ql_stub_class_qldoc.mustache

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
{{#doc}}
44
* {{.}}
55
{{/doc}}
6-
{{#ql_internal}}
6+
{{#internal}}
77
* INTERNAL: Do not use.
8-
{{/ql_internal}}
8+
{{/internal}}
99
*/
1010
{{/has_qldoc}}

‎misc/codegen/templates/ql_stub_module_qldoc.mustache

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
/**
22
* This module provides a hand-modifiable wrapper around the generated class `{{name}}`.
3-
{{#ql_internal}}
3+
{{#internal}}
44
* INTERNAL: Do not use.
5-
{{/ql_internal}}
5+
{{/internal}}
66
*/

‎misc/codegen/test/test_ql.py

Lines changed: 3 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -147,28 +147,18 @@ def test_class_with_children():
147147
assert cls.has_children is True
148148

149149

150-
@pytest.mark.parametrize("doc,ql_internal,expected",
150+
@pytest.mark.parametrize("doc,internal,expected",
151151
[
152152
(["foo", "bar"], False, True),
153153
(["foo", "bar"], True, True),
154154
([], False, False),
155155
([], True, True),
156156
])
157-
def test_has_doc(doc, ql_internal, expected):
158-
stub = ql.Stub("Class", base_import="foo", import_prefix="bar", doc=doc, ql_internal=ql_internal)
157+
def test_has_doc(doc, internal, expected):
158+
stub = ql.Stub("Class", base_import="foo", import_prefix="bar", doc=doc, internal=internal)
159159
assert stub.has_qldoc is expected
160160

161161

162-
def test_property_with_description():
163-
prop = ql.Property("X", "int", description=["foo", "bar"])
164-
assert prop.has_description is True
165-
166-
167-
def test_class_without_description():
168-
prop = ql.Property("X", "int")
169-
assert prop.has_description is False
170-
171-
172162
def test_synth_accessor_has_first_constructor_param_marked():
173163
params = ["a", "b", "c"]
174164
x = ql.SynthUnderlyingAccessor("foo", "bar", params)

‎misc/codegen/test/test_qlgen.py

Lines changed: 33 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -157,8 +157,8 @@ def test_one_empty_internal_class(generate_classes):
157157
assert generate_classes([
158158
schema.Class("A", pragmas=["ql_internal"])
159159
]) == {
160-
"A.qll": (a_ql_stub(name="A", ql_internal=True),
161-
a_ql_class(name="A", final=True, ql_internal=True)),
160+
"A.qll": (a_ql_stub(name="A", internal=True),
161+
a_ql_class(name="A", final=True, internal=True)),
162162
}
163163

164164

@@ -202,11 +202,11 @@ def test_hierarchy_children(generate_children_implementations):
202202
schema.Class("C", bases=["A"], derived={"D"}, pragmas=["ql_internal"]),
203203
schema.Class("D", bases=["B", "C"]),
204204
]) == ql.GetParentImplementation(
205-
classes=[a_ql_class(name="A", ql_internal=True),
205+
classes=[a_ql_class(name="A", internal=True),
206206
a_ql_class(name="B", bases=["A"], imports=[
207207
stub_import_prefix + "A"]),
208208
a_ql_class(name="C", bases=["A"], imports=[
209-
stub_import_prefix + "A"], ql_internal=True),
209+
stub_import_prefix + "A"], internal=True),
210210
a_ql_class(name="D", final=True, bases=["B", "C"],
211211
imports=[stub_import_prefix + cls for cls in "BC"]),
212212
],
@@ -228,6 +228,21 @@ def test_single_property(generate_classes):
228228
}
229229

230230

231+
def test_internal_property(generate_classes):
232+
assert generate_classes([
233+
schema.Class("MyObject", properties=[
234+
schema.SingleProperty("foo", "bar", pragmas=["ql_internal"])]),
235+
]) == {
236+
"MyObject.qll": (a_ql_stub(name="MyObject"),
237+
a_ql_class(name="MyObject", final=True,
238+
properties=[
239+
ql.Property(singular="Foo", type="bar", tablename="my_objects",
240+
tableparams=["this", "result"], doc="foo of this my object",
241+
internal=True),
242+
])),
243+
}
244+
245+
231246
def test_children(generate_classes):
232247
assert generate_classes([
233248
schema.Class("FakeRoot"),
@@ -424,7 +439,8 @@ def test_class_dir(generate_classes):
424439
schema.Class("A", derived={"B"}, group=dir),
425440
schema.Class("B", bases=["A"]),
426441
]) == {
427-
f"{dir}/A.qll": (a_ql_stub(name="A", import_prefix="another.rel.path."), a_ql_class(name="A", dir=pathlib.Path(dir))),
442+
f"{dir}/A.qll": (
443+
a_ql_stub(name="A", import_prefix="another.rel.path."), a_ql_class(name="A", dir=pathlib.Path(dir))),
428444
"B.qll": (a_ql_stub(name="B"),
429445
a_ql_class(name="B", final=True, bases=["A"],
430446
imports=[stub_import_prefix + "another.rel.path.A"])),
@@ -878,9 +894,9 @@ def test_stub_on_class_with_synth_from_class(generate_classes):
878894
ql.SynthUnderlyingAccessor(argument="Entity", type="Raw::A", constructorparams=["result"]),
879895
]),
880896
a_ql_class(name="MyObject", final=True, properties=[
881-
ql.Property(singular="Foo", type="bar", tablename="my_objects", synth=True,
882-
tableparams=["this", "result"], doc="foo of this my object"),
883-
])),
897+
ql.Property(singular="Foo", type="bar", tablename="my_objects", synth=True,
898+
tableparams=["this", "result"], doc="foo of this my object"),
899+
])),
884900
}
885901

886902

@@ -895,9 +911,9 @@ def test_stub_on_class_with_synth_on_arguments(generate_classes):
895911
ql.SynthUnderlyingAccessor(argument="Label", type="string", constructorparams=["_", "_", "result"]),
896912
]),
897913
a_ql_class(name="MyObject", final=True, properties=[
898-
ql.Property(singular="Foo", type="bar", tablename="my_objects", synth=True,
899-
tableparams=["this", "result"], doc="foo of this my object"),
900-
])),
914+
ql.Property(singular="Foo", type="bar", tablename="my_objects", synth=True,
915+
tableparams=["this", "result"], doc="foo of this my object"),
916+
])),
901917
}
902918

903919

@@ -909,7 +925,8 @@ def test_synth_property(generate_classes):
909925
"MyObject.qll": (a_ql_stub(name="MyObject"),
910926
a_ql_class(name="MyObject", final=True,
911927
properties=[
912-
ql.Property(singular="Foo", type="bar", tablename="my_objects", synth=True,
928+
ql.Property(singular="Foo", type="bar", tablename="my_objects",
929+
synth=True,
913930
tableparams=["this", "result"], doc="foo of this my object"),
914931
])),
915932
}
@@ -934,9 +951,10 @@ def test_hideable_property(generate_classes):
934951
"Other.qll": (a_ql_stub(name="Other"),
935952
a_ql_class(name="Other", imports=[stub_import_prefix + "MyObject"],
936953
final=True, properties=[
937-
ql.Property(singular="X", type="MyObject", tablename="others", type_is_hideable=True,
938-
tableparams=["this", "result"], doc="x of this other"),
939-
])),
954+
ql.Property(singular="X", type="MyObject", tablename="others",
955+
type_is_hideable=True,
956+
tableparams=["this", "result"], doc="x of this other"),
957+
])),
940958
}
941959

942960

‎swift/ql/.generated.list

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎swift/ql/lib/codeql/swift/generated/MacroRole.qll

Lines changed: 4 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)