add kotlin to Java language guides

saritai · saritai · commit ee9873fdce68 · 2023-09-27T13:16:58.000-04:00
diff --git a/docs/codeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-java-programs.rst b/docs/codeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-java-programs.rst
@@ -1,6 +1,6 @@
 .. _abstract-syntax-tree-classes-for-working-with-java-programs:
 
-Abstract syntax tree classes for working with Java programs
+Abstract syntax tree classes for working with Java and Kotlin programs
 ===========================================================
 
 CodeQL has a large selection of classes for representing the abstract syntax tree of Java and Kotlin programs.
diff --git a/docs/codeql/codeql-language-guides/annotations-in-java.rst b/docs/codeql/codeql-language-guides/annotations-in-java.rst
@@ -1,9 +1,11 @@
 .. _annotations-in-java:
 
-Annotations in Java
+Annotations in Java and Kotlin
 ===================
 
-CodeQL databases of Java projects contain information about all annotations attached to program elements.
+CodeQL databases of Java/Kotlin projects contain information about all annotations attached to program elements.
+
+.. include:: ../reusables/kotlin-beta-note.rst
 
 About working with annotations
 ------------------------------
@@ -15,7 +17,7 @@ Annotations are represented by these CodeQL classes:
 -  The class ``AnnotationElement`` represents an annotation element, that is, a member of an annotation type.
 -  The class ``Annotation`` represents an annotation such as ``@Override``; annotation values can be accessed through member predicate ``getValue``.
 
-For example, the Java standard library defines an annotation ``SuppressWarnings`` that instructs the compiler not to emit certain kinds of warnings:
+For example, the Java/Kotlin standard library defines an annotation ``SuppressWarnings`` that instructs the compiler not to emit certain kinds of warnings:
 
 .. code-block:: java
 
@@ -101,7 +103,7 @@ As a first step, let's write a query that finds all ``@Override`` annotations. A
    where ann.getType().hasQualifiedName("java.lang", "Override")
    select ann
 
-As always, it is a good idea to try this query on a CodeQL database for a Java project to make sure it actually produces some results. On the earlier example, it should find the annotation on ``Sub1.m``. Next, we encapsulate the concept of an ``@Override`` annotation as a CodeQL class:
+As always, it is a good idea to try this query on a CodeQL database for a Java/Kotlin project to make sure it actually produces some results. On the earlier example, it should find the annotation on ``Sub1.m``. Next, we encapsulate the concept of an ``@Override`` annotation as a CodeQL class:
 
 ::
 
@@ -185,7 +187,7 @@ For more information about the class ``Call``, see ":doc:`Navigating the call gr
 Improvements
 ~~~~~~~~~~~~
 
-The Java standard library provides another annotation type ``java.lang.SupressWarnings`` that can be used to suppress certain categories of warnings. In particular, it can be used to turn off warnings about calls to deprecated methods. Therefore, it makes sense to improve our query to ignore calls to deprecated methods from inside methods that are marked with ``@SuppressWarnings("deprecation")``.
+The Java/Kotlin standard library provides another annotation type ``java.lang.SupressWarnings`` that can be used to suppress certain categories of warnings. In particular, it can be used to turn off warnings about calls to deprecated methods. Therefore, it makes sense to improve our query to ignore calls to deprecated methods from inside methods that are marked with ``@SuppressWarnings("deprecation")``.
 
 For instance, consider this slightly updated example:
 
diff --git a/docs/codeql/codeql-language-guides/codeql-for-java.rst b/docs/codeql/codeql-language-guides/codeql-for-java.rst
@@ -32,16 +32,16 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
 
 -  :doc:`Analyzing data flow in Java and Kotlin <analyzing-data-flow-in-java>`: You can use CodeQL to track the flow of data through a Java/Kotlin program to its use. 
 
--  :doc:`Java types <types-in-java>`: You can use CodeQL to find out information about data types used in Java code. This allows you to write queries to identify specific type-related issues.
+-  :doc:`Java and Kotlin types <types-in-java>`: You can use CodeQL to find out information about data types used in Java/Kotlin code. This allows you to write queries to identify specific type-related issues.
 
--  :doc:`Overflow-prone comparisons in Java <overflow-prone-comparisons-in-java>`: You can use CodeQL to check for comparisons in Java code where one side of the comparison is prone to overflow.
+-  :doc:`Overflow-prone comparisons in Java and Kotlin <overflow-prone-comparisons-in-java>`: You can use CodeQL to check for comparisons in Java/Kotlin code where one side of the comparison is prone to overflow.
 
 -  :doc:`Navigating the call graph <navigating-the-call-graph>`: CodeQL has classes for identifying code that calls other code, and code that can be called from elsewhere. This allows you to find, for example, methods that are never used.
 
--  :doc:`Annotations in Java <annotations-in-java>`: CodeQL databases of Java projects contain information about all annotations attached to program elements.
+-  :doc:`Annotations in Java and Kotlin <annotations-in-java>`: CodeQL databases of Java/Kotlin projects contain information about all annotations attached to program elements.
 
--  :doc:`Javadoc <javadoc>`: You can use CodeQL to find errors in Javadoc comments in Java code.
+-  :doc:`Javadoc <javadoc>`: You can use CodeQL to find errors in Javadoc comments in Java/Kotlin code.
 
--  :doc:`Working with source locations <working-with-source-locations>`: You can use the location of entities within Java code to look for potential errors. Locations allow you to deduce the presence, or absence, of white space which, in some cases, may indicate a problem.
+-  :doc:`Working with source locations <working-with-source-locations>`: You can use the location of entities within Java/Kotlin code to look for potential errors. Locations allow you to deduce the presence, or absence, of white space which, in some cases, may indicate a problem.
 
 -  :doc:`Abstract syntax tree classes for working with Java and Kotlin programs <abstract-syntax-tree-classes-for-working-with-java-programs>`: CodeQL has a large selection of classes for representing the abstract syntax tree of Java/Kotlin programs.
diff --git a/docs/codeql/codeql-language-guides/codeql-library-for-java.rst b/docs/codeql/codeql-language-guides/codeql-library-for-java.rst
@@ -5,6 +5,8 @@ CodeQL library for Java and Kotlin
 
 When you're analyzing a Java/Kotlin program, you can make use of the large collection of classes in the CodeQL library for Java/Kotlin.
 
+.. include:: ../reusables/kotlin-beta-note.rst
+
 About the CodeQL library for Java and Kotlin
 --------------------------------------------
 
diff --git a/docs/codeql/codeql-language-guides/customizing-library-models-for-java.rst b/docs/codeql/codeql-language-guides/customizing-library-models-for-java.rst
@@ -3,12 +3,14 @@
 :orphan:
 :nosearch:
 
-Customizing Library Models for Java
+Customizing Library Models for Java and Kotlin 
 ===================================
 
 .. include:: ../reusables/beta-note-customizing-library-models.rst
 
-The Java analysis can be customized by adding library models (summaries, sinks and sources) in data extension files.
+.. include:: ../reusables/kotlin-beta-note.rst
+
+The Java/Kotlin analysis can be customized by adding library models (summaries, sinks and sources) in data extension files.
 A model is a definition of a behavior of a library element, such as a method, that is used to improve the data flow analysis precision by identifying more results.
 Most of the security related queries are taint tracking queries that try to find paths from a source of untrusted input to a sink that represents a vulnerability. Sources are the starting points of a taint tracking data flow analysis, and sinks are the end points of a taint tracking data flow analysis.
 
@@ -30,7 +32,7 @@ A data extension file for Java is a YAML file in the form:
 
 Data extensions contribute to the extensible predicates defined in the CodeQL library. For more information on how to define data extensions and extensible predicates as well as how to wire them up, see the :ref:`data-extensions` documentation.
 
-The CodeQL library for Java exposes the following extensible predicates:
+The CodeQL library for Java/Kotlin exposes the following extensible predicates:
 
 - **sourceModel**\(package, type, subtypes, name, signature, ext, output, kind, provenance). This is used for **source** models.
 - **sinkModel**\(package, type, subtypes, name, signature, ext, input, kind, provenance). This is used for **sink** models.
@@ -48,7 +50,7 @@ Example: Taint sink in the **java.sql** package
 
 In this example we will show how to model the argument of the **execute** method as a SQL injection sink.
 This is the **execute** method in the **Statement** class, which is located in the **java.sql** package.
-Note that this sink is already added to the CodeQL Java analysis.
+Note that this sink is already added to the CodeQL Java/Kotlin analysis.
 
 .. code-block:: java
 
@@ -89,7 +91,7 @@ Example: Taint source from the **java.net** package
 ----------------------------------------------------
 In this example we show how to model the return value from the **getInputStream** method as a **remote** source.
 This is the **getInputStream** method in the **Socket** class, which is located in the **java.net** package.
-Note that this source is already added to the CodeQL Java analysis.
+Note that this source is already added to the CodeQL Java/Kotlin analysis.
 
 .. code-block:: java
 
@@ -130,7 +132,7 @@ Example: Add flow through the **concat** method
 ------------------------------------------------
 In this example we show how to model flow through a method for a simple case.
 This pattern covers many of the cases where we need to define flow through a method.
-Note that the flow through the **concat** method is already added to the CodeQL Java analysis.
+Note that the flow through the **concat** method is already added to the CodeQL Java/Kotlin analysis.
 
 .. code-block:: java
 
@@ -178,7 +180,7 @@ Example: Add flow through the **map** method
 ---------------------------------------------
 In this example, we will see a more complex example of modeling flow through a method.
 This pattern shows how to model flow through higher order methods and collection types.
-Note that the flow through the **map** method is already added to the CodeQL Java analysis.
+Note that the flow through the **map** method is already added to the CodeQL Java/Kotlin analysis.
 
 .. code-block:: java
 
@@ -238,7 +240,7 @@ Example: Add a **neutral** method
 ----------------------------------
 In this example we will show how to model the **now** method as being neutral with respect to flow.
 A neutral model is used to define that there is no flow through a method.
-Note that the neutral model for the **now** method is already added to the CodeQL Java analysis.
+Note that the neutral model for the **now** method is already added to the CodeQL Java/Kotlin analysis.
 
 .. code-block:: java
 
diff --git a/docs/codeql/codeql-language-guides/javadoc.rst b/docs/codeql/codeql-language-guides/javadoc.rst
@@ -3,7 +3,9 @@
 Javadoc
 =======
 
-You can use CodeQL to find errors in Javadoc comments in Java code.
+You can use CodeQL to find errors in Javadoc comments in Java/Kotlin code.
+
+.. include:: ../reusables/kotlin-beta-note.rst
 
 About analyzing Javadoc
 -----------------------
diff --git a/docs/codeql/codeql-language-guides/navigating-the-call-graph.rst b/docs/codeql/codeql-language-guides/navigating-the-call-graph.rst
@@ -8,7 +8,7 @@ CodeQL has classes for identifying code that calls other code, and code that can
 Call graph classes
 ------------------
 
-The CodeQL library for Java provides two abstract classes for representing a program's call graph: ``Callable`` and ``Call``. The former is simply the common superclass of ``Method`` and ``Constructor``, the latter is a common superclass of ``MethodAccess``, ``ClassInstanceExpression``, ``ThisConstructorInvocationStmt`` and ``SuperConstructorInvocationStmt``. Simply put, a ``Callable`` is something that can be invoked, and a ``Call`` is something that invokes a ``Callable``.
+The CodeQL library for Java/Kotlin provides two abstract classes for representing a program's call graph: ``Callable`` and ``Call``. The former is simply the common superclass of ``Method`` and ``Constructor``, the latter is a common superclass of ``MethodAccess``, ``ClassInstanceExpression``, ``ThisConstructorInvocationStmt`` and ``SuperConstructorInvocationStmt``. Simply put, a ``Callable`` is something that can be invoked, and a ``Call`` is something that invokes a ``Callable``.
 
 For example, in the following program all callables and calls have been annotated with comments:
 
@@ -88,7 +88,7 @@ This simple query typically returns a large number of results.
 
    We have to use ``polyCalls`` instead of ``calls`` here: we want to be reasonably sure that ``callee`` is not called, either directly or via overriding.
 
-Running this query on a typical Java project results in lots of hits in the Java standard library. This makes sense, since no single client program uses every method of the standard library. More generally, we may want to exclude methods and constructors from compiled libraries. We can use the predicate ``fromSource`` to check whether a compilation unit is a source file, and refine our query:
+Running this query on a typical Java/Kotlin project results in lots of hits in the Java/Kotlin standard library. This makes sense, since no single client program uses every method of the standard library. More generally, we may want to exclude methods and constructors from compiled libraries. We can use the predicate ``fromSource`` to check whether a compilation unit is a source file, and refine our query:
 
 .. code-block:: ql
 
diff --git a/docs/codeql/codeql-language-guides/overflow-prone-comparisons-in-java.rst b/docs/codeql/codeql-language-guides/overflow-prone-comparisons-in-java.rst
@@ -1,9 +1,11 @@
 .. _overflow-prone-comparisons-in-java:
 
-Overflow-prone comparisons in Java
+Overflow-prone comparisons in Java and Kotlin
 ==================================
 
-You can use CodeQL to check for comparisons in Java code where one side of the comparison is prone to overflow.
+You can use CodeQL to check for comparisons in Java/Kotlin code where one side of the comparison is prone to overflow.
+
+.. include:: ../reusables/kotlin-beta-note.rst
 
 About this article
 ------------------
diff --git a/docs/codeql/codeql-language-guides/types-in-java.rst b/docs/codeql/codeql-language-guides/types-in-java.rst
@@ -1,9 +1,11 @@
 .. _types-in-java:
 
-Types in Java
+Types in Java and Kotlin
 =============
 
-You can use CodeQL to find out information about data types used in Java code. This allows you to write queries to identify specific type-related issues.
+You can use CodeQL to find out information about data types used in Java/Kotlin code. This allows you to write queries to identify specific type-related issues.
+
+.. include:: ../reusables/kotlin-beta-note.rst
 
 About working with Java types
 -----------------------------
diff --git a/docs/codeql/codeql-language-guides/working-with-source-locations.rst b/docs/codeql/codeql-language-guides/working-with-source-locations.rst
@@ -3,7 +3,9 @@
 Working with source locations
 =============================
 
-You can use the location of entities within Java code to look for potential errors. Locations allow you to deduce the presence, or absence, of white space which, in some cases, may indicate a problem.
+You can use the location of entities within Java/Kotlin code to look for potential errors. Locations allow you to deduce the presence, or absence, of white space which, in some cases, may indicate a problem.
+
+.. include:: ../reusables/kotlin-beta-note.rst
 
 About source locations
 ----------------------
@@ -175,7 +177,7 @@ Now we can extend our query to discard results where the outer and the inner exp
        wsinner > wsouter
    select outer, "Whitespace around nested operators contradicts precedence."
 
-Notice that we again use ``getOp``, this time to determine whether two binary expressions have the same operator. Running our improved query now finds the Java standard library bug described in the Overview. It also flags up the following suspicious code in `Hadoop HBase <https://hbase.apache.org/>`__:
+Notice that we again use ``getOp``, this time to determine whether two binary expressions have the same operator. Running our improved query now finds the Java/Kotlin standard library bug described in the Overview. It also flags up the following suspicious code in `Hadoop HBase <https://hbase.apache.org/>`__:
 
 .. code-block:: java
 
