Rust: Add comments for type inference

Author: paldepind

rust/ql/lib/codeql/rust/internal/TypeInference.qll

@@ -903,7 +903,7 @@ private module Cached {
   }
 
   /**
-   * Gets a method that the method call `mce` infers to, if any.
+   * Gets a method that the method call `mce` resolves to, if any.
    */
   cached
   Function resolveMethodCallExpr(MethodCallExpr mce) {
@@ -917,7 +917,7 @@ private module Cached {
   }
 
   /**
-   * Gets the record field that the field expression `fe` infers to, if any.
+   * Gets the record field that the field expression `fe` resolves to, if any.
    */
   cached
   RecordField resolveRecordFieldExpr(FieldExpr fe) {
@@ -933,7 +933,7 @@ private module Cached {
   }
 
   /**
-   * Gets the tuple field that the field expression `fe` infers to, if any.
+   * Gets the tuple field that the field expression `fe` resolves to, if any.
    */
   cached
   TupleField resolveTupleFieldExpr(FieldExpr fe) {

shared/typeinference/codeql/typeinference/internal/TypeInference.qll

@@ -651,7 +651,7 @@ module Make1<LocationSig Location, InputSig1<Location> Input1> {
        *
        * class Sub<T4> : Mid<C<T4>> { }
        *
-       *    new Sub<int>().Method();
+       *    new Sub<int>().Method(); // Note: `Sub<int>` is a subtype of `Base<C<C<int>>>`
        * // ^^^^^^^^^^^^^^^^^^^^^^^ `a`
        * ```
        *
@@ -675,6 +675,11 @@ module Make1<LocationSig Location, InputSig1<Location> Input1> {
         )
       }
 
+      /**
+       * Holds if for `a` and corresponding `target`, the type parameter `tp` is
+       * matched by a type argument at the access with type `t` and type path
+       * `path`.
+       */
       pragma[nomagic]
       private predicate explicitTypeMatch(
         Access a, Declaration target, TypePath path, Type t, TypeParameter tp
@@ -687,17 +692,23 @@ module Make1<LocationSig Location, InputSig1<Location> Input1> {
       private predicate implicitTypeMatch(
         Access a, Declaration target, TypePath path, Type t, TypeParameter tp
       ) {
+        // We can get the type of `tp` from one of the access positions
         directTypeMatch(a, target, path, t, tp)
         or
+        // We can get the type of `tp` by going up the type hiearchy
         baseTypeMatch(a, target, path, t, tp)
       }
 
       pragma[inline]
       private predicate typeMatch(
         Access a, Declaration target, TypePath path, Type t, TypeParameter tp
       ) {
+        // A type given at the access corresponds directly to the type parameter
+        // at the target.
         explicitTypeMatch(a, target, path, t, tp)
         or
+        // No explicit type argument, so we deduce the parameter from other
+        // information
         implicitTypeMatch(a, target, path, t, tp)
       }
 
@@ -742,12 +753,14 @@ module Make1<LocationSig Location, InputSig1<Location> Input1> {
       pragma[nomagic]
       Type inferAccessType(Access a, AccessPosition apos, TypePath path) {
         exists(DeclarationPosition dpos | accessDeclarationPositionMatch(apos, dpos) |
+          // A suffix of `path` leads to a type parameter in the target
           exists(Declaration target, TypePath prefix, TypeParameter tp, TypePath suffix |
             tp = target.getDeclaredType(pragma[only_bind_into](dpos), prefix) and
             path = prefix.append(suffix) and
             typeMatch(a, target, suffix, result, tp)
           )
           or
+          // `path` corresponds directly to a concrete type in the declaration
           exists(Declaration target |
             result = target.getDeclaredType(pragma[only_bind_into](dpos), path) and
             target = a.getTarget() and