Python: Make QLDoc for TObject.qll visible.

Author: tausbn

python/ql/src/semmle/python/objects/TObject.qll

@@ -1,3 +1,5 @@
+/** Contains the internal IPA type backing the various values tracked by the points-to implementation. */
+
 import python
 private import semmle.python.types.Builtins
 private import semmle.python.objects.ObjectInternal
@@ -10,19 +12,19 @@ private import semmle.python.pointsto.PointsToContext
  */
 cached
 newtype TObject =
-    /* Builtin class objects */
+    /** Builtin class objects */
     TBuiltinClassObject(Builtin bltn) {
         bltn.isClass() and
         not bltn = Builtin::unknownType() and
         not bltn = Builtin::special("type")
     } or
-    /* Builtin function objects (module members) */
+    /** Builtin function objects (module members) */
     TBuiltinFunctionObject(Builtin bltn) { bltn.isFunction() } or
-    /* Builtin method objects (class members) */
+    /** Builtin method objects (class members) */
     TBuiltinMethodObject(Builtin bltn) { bltn.isMethod() } or
-    /* Builtin module objects */
+    /** Builtin module objects */
     TBuiltinModuleObject(Builtin bltn) { bltn.isModule() } or
-    /* Other builtin objects from the interpreter */
+    /** Other builtin objects from the interpreter */
     TBuiltinOpaqueObject(Builtin bltn) {
         not bltn.isClass() and
         not bltn.isFunction() and
@@ -34,31 +36,31 @@ newtype TObject =
         not exists(bltn.strValue()) and
         not py_special_objects(bltn, _)
     } or
-    /* Python function objects (including lambdas) */
+    /** Python function objects (including lambdas) */
     TPythonFunctionObject(ControlFlowNode callable) { callable.getNode() instanceof CallableExpr } or
-    /* Python class objects */
+    /** Python class objects */
     TPythonClassObject(ControlFlowNode classexpr) { classexpr.getNode() instanceof ClassExpr } or
-    /* Package objects */
+    /** Package objects */
     TPackageObject(Folder f) { isPreferredModuleForName(f, _) } or
-    /* Python module objects */
+    /** Python module objects */
     TPythonModule(Module m) {
         not m.isPackage() and
         isPreferredModuleForName(m.getFile(), _) and
         not exists(SyntaxError se | se.getFile() = m.getFile())
     } or
-    /* `True` */
+    /** `True` */
     TTrue() or
-    /* `False` */
+    /** `False` */
     TFalse() or
-    /* `None` */
+    /** `None` */
     TNone() or
-    /* Represents any value about which nothing useful is known */
+    /** Represents any value about which nothing useful is known */
     TUnknown() or
-    /* Represents any value known to be a class, but not known to be any specific class */
+    /** Represents any value known to be a class, but not known to be any specific class */
     TUnknownClass() or
-    /* Represents the absence of a value. Used by points-to for tracking undefined variables */
+    /** Represents the absence of a value. Used by points-to for tracking undefined variables */
     TUndefined() or
-    /* The integer `n` */
+    /** The integer `n` */
     TInt(int n) {
         // Powers of 2 are used for flags
         is_power_2(n)
@@ -76,9 +78,9 @@ newtype TObject =
         or
         n = any(Builtin b).intValue()
     } or
-    /* The float `f` */
+    /** The float `f` */
     TFloat(float f) { f = any(FloatLiteral num).getValue() } or
-    /* The unicode string `s` */
+    /** The unicode string `s` */
     TUnicode(string s) {
         // Any string explicitly mentioned in the source code.
         exists(StrConst str |
@@ -94,7 +96,7 @@ newtype TObject =
         or
         s = "__main__"
     } or
-    /* The byte string `s` */
+    /** The byte string `s` */
     TBytes(string s) {
         // Any string explicitly mentioned in the source code.
         exists(StrConst str |
@@ -110,74 +112,74 @@ newtype TObject =
         or
         s = "__main__"
     } or
-    /* An instance of `cls`, instantiated at `instantiation` given the `context`. */
+    /** An instance of `cls`, instantiated at `instantiation` given the `context`. */
     TSpecificInstance(ControlFlowNode instantiation, ClassObjectInternal cls, PointsToContext context) {
         PointsToInternal::pointsTo(instantiation.(CallNode).getFunction(), context, cls, _) and
         cls.isSpecial() = false
         or
         literal_instantiation(instantiation, cls, context)
     } or
-    /* A non-specific instance `cls` which enters the scope at `def` given the callee `context`. */
+    /** A non-specific instance `cls` which enters the scope at `def` given the callee `context`. */
     TSelfInstance(ParameterDefinition def, PointsToContext context, PythonClassObjectInternal cls) {
         self_parameter(def, context, cls)
     } or
-    /* A bound method */
+    /** A bound method */
     TBoundMethod(ObjectInternal self, CallableObjectInternal function) {
         any(ObjectInternal obj).binds(self, _, function) and
         function.isDescriptor() = true
     } or
-    /* Represents any value whose class is known, but nothing else */
+    /** Represents any value whose class is known, but nothing else */
     TUnknownInstance(BuiltinClassObjectInternal cls) {
         cls != ObjectInternal::superType() and
         cls != ObjectInternal::builtin("bool") and
         cls != ObjectInternal::noneType()
     } or
-    /* Represents an instance of `super` */
+    /** Represents an instance of `super` */
     TSuperInstance(ObjectInternal self, ClassObjectInternal startclass) {
         super_instantiation(_, self, startclass, _)
     } or
-    /* Represents an instance of `classmethod` */
+    /** Represents an instance of `classmethod` */
     TClassMethod(CallNode instantiation, CallableObjectInternal function) {
         class_method(instantiation, function, _)
     } or
-    /* Represents an instance of `staticmethod` */
+    /** Represents an instance of `staticmethod` */
     TStaticMethod(CallNode instantiation, CallableObjectInternal function) {
         static_method(instantiation, function, _)
     } or
-    /* Represents a builtin tuple */
+    /** Represents a builtin tuple */
     TBuiltinTuple(Builtin bltn) { bltn.getClass() = Builtin::special("tuple") } or
-    /* Represents a tuple in the Python source */
+    /** Represents a tuple in the Python source */
     TPythonTuple(TupleNode origin, PointsToContext context) {
         origin.isLoad() and
         context.appliesTo(origin)
     } or
-    /* Varargs tuple */
+    /** Varargs tuple */
     TVarargsTuple(CallNode call, PointsToContext context, int offset, int length) {
         InterProceduralPointsTo::varargs_tuple(call, context, _, _, offset, length)
     } or
-    /* `type` */
+    /** `type` */
     TType() or
-    /* Represents an instance of `property` */
+    /** Represents an instance of `property` */
     TProperty(CallNode call, Context ctx, CallableObjectInternal getter) {
         PointsToInternal::pointsTo(call.getFunction(), ctx, ObjectInternal::property(), _) and
         PointsToInternal::pointsTo(call.getArg(0), ctx, getter, _)
     } or
-    /* Represents the `setter` or `deleter` method of a property object. */
+    /** Represents the `setter` or `deleter` method of a property object. */
     TPropertySetterOrDeleter(PropertyInternal property, string method) {
         exists(AttrNode attr | PointsToInternal::pointsTo(attr.getObject(method), _, property, _)) and
         (method = "setter" or method = "deleter")
     } or
-    /* Represents a dynamically created class */
+    /** Represents a dynamically created class */
     TDynamicClass(CallNode instantiation, ClassObjectInternal metacls, PointsToContext context) {
         PointsToInternal::pointsTo(instantiation.getFunction(), context, metacls, _) and
         not count(instantiation.getAnArg()) = 1 and
         Types::getMro(metacls).contains(TType())
     } or
-    /* Represents `sys.version_info`. Acts like a tuple with a range of values depending on the version being analysed. */
+    /** Represents `sys.version_info`. Acts like a tuple with a range of values depending on the version being analysed. */
     TSysVersionInfo() or
-    /* Represents a module that is inferred to perhaps exist, but is not present in the database. */
+    /** Represents a module that is inferred to perhaps exist, but is not present in the database. */
     TAbsentModule(string name) { missing_imported_module(_, _, name) } or
-    /* Represents an attribute of a module that is inferred to perhaps exist, but is not present in the database. */
+    /** Represents an attribute of a module that is inferred to perhaps exist, but is not present in the database. */
     TAbsentModuleAttribute(AbsentModuleObjectInternal mod, string attrname) {
         (
             PointsToInternal::pointsTo(any(AttrNode attr).getObject(attrname), _, mod, _)
@@ -189,16 +191,17 @@ newtype TObject =
             not common_module_name(modname + "." + attrname)
         )
     } or
-    /* Opaque object representing the result of calling a decorator on a function that we don't understand */
+    /** Opaque object representing the result of calling a decorator on a function that we don't understand */
     TDecoratedFunction(CallNode call) { call.isFunctionDecoratorCall() } or
-    /* Represents a subscript operation applied to a type. For type-hint analysis */
+    /** Represents a subscript operation applied to a type. For type-hint analysis */
     TSubscriptedType(ObjectInternal generic, ObjectInternal index) {
         isType(generic) and
         generic.isNotSubscriptedType() and
         index.isNotSubscriptedType() and
         Expressions::subscriptPartsPointsTo(_, _, generic, index)
     }
 
+/** Holds if the object `t` is a type. */
 predicate isType(ObjectInternal t) {
     t.isClass() = true
     or
@@ -421,7 +424,7 @@ predicate missing_imported_module(ControlFlowNode imp, Context ctx, string name)
     )
 }
 
-/*
+/**
  * Helper for missing modules to determine if name `x.y` is a module `x.y` or
  * an attribute `y` of module `x`. This list should be added to as required.
  */