@@ -4,7 +4,21 @@ import semmle.code.cpp.Initializer
44private import semmle.code.cpp.internal.ResolveClass
55
66/**
7- * A C/C++ variable.
7+ * A C/C++ variable. For example, in the following code there are four
8+ * variables, `a`, `b`, `c` and `d`:
9+ * ```
10+ * extern int a;
11+ * int a;
12+ *
13+ * void myFunction(int b) {
14+ * int c;
15+ * }
16+ *
17+ * namespace N {
18+ * extern int d;
19+ * int d = 1;
20+ * }
21+ * ```
822 *
923 * For local variables, there is a one-to-one correspondence between
1024 * `Variable` and `VariableDeclarationEntry`.
@@ -162,7 +176,22 @@ class Variable extends Declaration, @variable {
162176}
163177
164178/**
165- * A particular declaration or definition of a C/C++ variable.
179+ * A particular declaration or definition of a C/C++ variable. For example, in
180+ * the following code there are six variable declaration entries - two each for
181+ * `a` and `d`, and one each for `b` and `c`:
182+ * ```
183+ * extern int a;
184+ * int a;
185+ *
186+ * void myFunction(int b) {
187+ * int c;
188+ * }
189+ *
190+ * namespace N {
191+ * extern int d;
192+ * int d = 1;
193+ * }
194+ * ```
166195 */
167196class VariableDeclarationEntry extends DeclarationEntry , @var_decl {
168197 override Variable getDeclaration ( ) { result = getVariable ( ) }
@@ -183,13 +212,13 @@ class VariableDeclarationEntry extends DeclarationEntry, @var_decl {
183212 * because the parameter may have a different name in the declaration
184213 * than in the definition. For example:
185214 *
186- * ```
187- * // Declaration. Parameter is named "x".
188- * int f(int x);
215+ * ```
216+ * // Declaration. Parameter is named "x".
217+ * int f(int x);
189218 *
190- * // Definition. Parameter is named "y".
191- * int f(int y) { return y; }
192- * ```
219+ * // Definition. Parameter is named "y".
220+ * int f(int y) { return y; }
221+ * ```
193222 */
194223 override string getName ( ) { var_decls ( underlyingElement ( this ) , _, _, result , _) and result != "" }
195224
@@ -215,7 +244,13 @@ class VariableDeclarationEntry extends DeclarationEntry, @var_decl {
215244
216245/**
217246 * A parameter as described within a particular declaration or definition
218- * of a C/C++ function.
247+ * of a C/C++ function. For example the declaration of `a` in the following
248+ * code:
249+ * ```
250+ * void myFunction(int a) {
251+ * int b;
252+ * }
253+ * ```
219254 */
220255class ParameterDeclarationEntry extends VariableDeclarationEntry {
221256 ParameterDeclarationEntry ( ) { param_decl_bind ( underlyingElement ( this ) , _, _) }
@@ -272,8 +307,17 @@ class ParameterDeclarationEntry extends VariableDeclarationEntry {
272307
273308/**
274309 * A C/C++ variable with block scope [N4140 3.3.3]. In other words, a local
275- * variable or a function parameter. Local variables can be static; use the
276- * `isStatic` member predicate to detect those.
310+ * variable or a function parameter. For example, the variables `a`, `b` and
311+ * `c` in the following code:
312+ * ```
313+ * void myFunction(int a) {
314+ * int b;
315+ * static int c;
316+ * }
317+ * ```
318+ *
319+ * Local variables can be static; use the `isStatic` member predicate to
320+ * detect those.
277321 */
278322class LocalScopeVariable extends Variable , @localscopevariable {
279323 /** Gets the function to which this variable belongs. */
@@ -292,6 +336,14 @@ deprecated class StackVariable extends Variable {
292336/**
293337 * A C/C++ local variable. In other words, any variable that has block
294338 * scope [N4140 3.3.3], but is not a parameter of a `Function` or `CatchBlock`.
339+ * For example the variables `b` and `c` in the following code:
340+ * ```
341+ * void myFunction(int a) {
342+ * int b;
343+ * static int c;
344+ * }
345+ * ```
346+ *
295347 * Local variables can be static; use the `isStatic` member predicate to detect
296348 * those.
297349 *
@@ -310,7 +362,15 @@ class LocalVariable extends LocalScopeVariable, @localvariable {
310362}
311363
312364/**
313- * A C/C++ variable which has global scope or namespace scope.
365+ * A C/C++ variable which has global scope or namespace scope. For example the
366+ * variables `a` and `b` in the following code:
367+ * ```
368+ * int a;
369+ *
370+ * namespace N {
371+ * int b;
372+ * }
373+ * ```
314374 */
315375class GlobalOrNamespaceVariable extends Variable , @globalvariable {
316376 override string getName ( ) { globalvariables ( underlyingElement ( this ) , _, result ) }
@@ -321,7 +381,15 @@ class GlobalOrNamespaceVariable extends Variable, @globalvariable {
321381}
322382
323383/**
324- * A C/C++ variable which has namespace scope.
384+ * A C/C++ variable which has namespace scope. For example the variable `b`
385+ * in the following code:
386+ * ```
387+ * int a;
388+ *
389+ * namespace N {
390+ * int b;
391+ * }
392+ * ```
325393 */
326394class NamespaceVariable extends GlobalOrNamespaceVariable {
327395 NamespaceVariable ( ) {
@@ -330,7 +398,15 @@ class NamespaceVariable extends GlobalOrNamespaceVariable {
330398}
331399
332400/**
333- * A C/C++ variable which has global scope.
401+ * A C/C++ variable which has global scope. For example the variable `a`
402+ * in the following code:
403+ * ```
404+ * int a;
405+ *
406+ * namespace N {
407+ * int b;
408+ * }
409+ * ```
334410 *
335411 * Note that variables declared in anonymous namespaces have namespace scope,
336412 * even though they are accessed in the same manner as variables declared in
@@ -341,7 +417,15 @@ class GlobalVariable extends GlobalOrNamespaceVariable {
341417}
342418
343419/**
344- * A C structure member or C++ member variable.
420+ * A C structure member or C++ member variable. For example the member
421+ * variables `m` and `s` in the following code:
422+ * ```
423+ * class MyClass {
424+ * public:
425+ * int m;
426+ * static int s;
427+ * };
428+ * ```
345429 *
346430 * This includes static member variables in C++. To exclude static member
347431 * variables, use `Field` instead of `MemberVariable`.
@@ -395,7 +479,12 @@ deprecated class FunctionPointerMemberVariable extends MemberVariable {
395479}
396480
397481/**
398- * A C++14 variable template.
482+ * A C++14 variable template. For example, in the following code the variable
483+ * template `v` defines a family of variables:
484+ * ```
485+ * template<class T>
486+ * T v;
487+ * ```
399488 */
400489class TemplateVariable extends Variable {
401490 TemplateVariable ( ) { is_variable_template ( underlyingElement ( this ) ) }
@@ -410,7 +499,24 @@ class TemplateVariable extends Variable {
410499 * A non-static local variable or parameter that is not part of an
411500 * uninstantiated template. Uninstantiated templates are purely syntax, and
412501 * only on instantiation will they be complete with information about types,
413- * conversions, call targets, etc.
502+ * conversions, call targets, etc. For example in the following code, the
503+ * variables `a` in `myFunction` and `b` in the instantiation
504+ * `myTemplateFunction<int>`, but not `b` in the template
505+ * `myTemplateFunction<T>`:
506+ * ```
507+ * void myFunction() {
508+ * T a;
509+ * }
510+ *
511+ * template<type T>
512+ * void myTemplateFunction() {
513+ * T b;
514+ * }
515+ *
516+ * ...
517+ *
518+ * myTemplateFunction<int>();
519+ * ```
414520 */
415521class SemanticStackVariable extends LocalScopeVariable {
416522 SemanticStackVariable ( ) {
0 commit comments