From 88eb91aa70abf27fd8b328cadf31ca6ec74ffb03 Mon Sep 17 00:00:00 2001
From: Rasmus Wriedt Larsen <rasmuswl@github.com>
Date: Tue, 12 Sep 2023 15:13:20 +0200
Subject: [PATCH] Python: Improve docs/names around already modeled classes

---
 .../frameworks/internal/SubclassFinder.qll     | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/python/ql/lib/semmle/python/frameworks/internal/SubclassFinder.qll b/python/ql/lib/semmle/python/frameworks/internal/SubclassFinder.qll
index 2752571a7a4..0fb84561c3b 100644
--- a/python/ql/lib/semmle/python/frameworks/internal/SubclassFinder.qll
+++ b/python/ql/lib/semmle/python/frameworks/internal/SubclassFinder.qll
@@ -64,6 +64,10 @@ module NotExposed {
 
   bindingset[this]
   abstract class FindSubclassesSpec extends string {
+    /**
+     * Gets an API node for a class that has already been modeled. You can include
+     * `.getASubclass*()` without causing problems, but it is not needed.
+     */
     abstract API::Node getAlreadyModeledClass();
 
     FindSubclassesSpec getSuperClass() { none() }
@@ -94,8 +98,14 @@ module NotExposed {
     )
   }
 
+  /**
+   * Holds if `fullyQualifiedName` is already explicitly modeled in the `spec`.
+   *
+   * For specs that do `.getASubclass*()`, items found by following a `.getASubclass`
+   * edge will not be considered explicitly modeled.
+   */
   bindingset[fullyQualifiedName]
-  predicate alreadyModeled(FindSubclassesSpec spec, string fullyQualifiedName) {
+  predicate alreadyExplicitlyModeled(FindSubclassesSpec spec, string fullyQualifiedName) {
     fullyQualifiedToApiGraphPath(fullyQualifiedName) = spec.getAlreadyModeledClass().getPath()
   }
 
@@ -153,7 +163,7 @@ module NotExposed {
       or
       mod.declaredInAll(importMember.getName())
     ) and
-    not alreadyModeled(spec, newAliasFullyQualified) and
+    not alreadyExplicitlyModeled(spec, newAliasFullyQualified) and
     isNonTestProjectCode(importMember)
   }
 
@@ -181,7 +191,7 @@ module NotExposed {
       or
       mod.declaredInAll(relevantName)
     ) and
-    not alreadyModeled(spec, newAliasFullyQualified) and
+    not alreadyExplicitlyModeled(spec, newAliasFullyQualified) and
     isNonTestProjectCode(importStar)
   }
 
@@ -194,7 +204,7 @@ module NotExposed {
     classExpr.getScope() = mod and
     newSubclassQualified = mod.getName() + "." + classExpr.getName() and
     loc = classExpr.getLocation() and
-    not alreadyModeled(spec, newSubclassQualified) and
+    not alreadyExplicitlyModeled(spec, newSubclassQualified) and
     isNonTestProjectCode(classExpr)
   }
 }