Swift: QLDoc Type.qll, TypeDecl.qll, and deprecate one of the predicates.

Author: geoffw0

swift/ql/lib/codeql/swift/elements/decl/TypeDecl.qll

@@ -2,16 +2,44 @@ private import codeql.swift.generated.decl.TypeDecl
 private import codeql.swift.elements.type.AnyGenericType
 private import swift
 
+/**
+ * A Swift type declaration, for example a class, struct, enum or protocol
+ * declaration.
+ *
+ * Type declarations are distinct from types. A type declaration represents
+ * the code that declares a type, for example:
+ * ```
+ * class MyClass {
+ *   ...
+ * }
+ * ```
+ * Not all types have type declarations, for example built-in types do not
+ * have type declarations.
+ */
 class TypeDecl extends Generated::TypeDecl {
   override string toString() { result = this.getName() }
 
+  /**
+   * Gets the declaration of the `index`th base type of this type declaration (0-based).
+   */
   TypeDecl getBaseTypeDecl(int i) { result = this.getBaseType(i).(AnyGenericType).getDeclaration() }
 
+  /**
+   * Gets the declaration of any of the base types of this type declaration.
+   */
   TypeDecl getABaseTypeDecl() { result = this.getBaseTypeDecl(_) }
 
-  TypeDecl getDerivedTypeDecl(int i) { result.getBaseTypeDecl(i) = this }
+  /**
+   * Gets a declaration that has this type as its `index`th base type.
+   *
+   * DEPRECATED: The index is not very meaningful here. Use `getADerivedTypeDecl` or `getBaseTypeDecl`.
+   */
+  deprecated TypeDecl getDerivedTypeDecl(int i) { result.getBaseTypeDecl(i) = this }
 
-  TypeDecl getADerivedTypeDecl() { result = this.getDerivedTypeDecl(_) }
+  /**
+   * Gets the declaration of any type derived from this type declaration.
+   */
+  TypeDecl getADerivedTypeDecl() { result.getBaseTypeDecl(_) = this }
 
   /**
    * Gets the full name of this `TypeDecl`. For example in:

swift/ql/lib/codeql/swift/elements/type/Type.qll

@@ -1,5 +1,10 @@
 private import codeql.swift.generated.type.Type
 
+/**
+ * A Swift type.
+ *
+ * This QL class is the root of the Swift type hierarchy.
+ */
 class Type extends Generated::Type {
   override string toString() { result = this.getName() }