Merge pull request github#3055 from jf205/codeql-migration-2162

CodeQL docs: update titles and small content changes (CodeQL queries)

Author: jf205

docs/language/learn-ql/cpp/dataflow.rst

@@ -6,7 +6,7 @@ You can use data-flow analysis to track the flow of potentially malicious or ins
 About data flow
 ---------------
 
-Data flow analysis computes the possible values that a variable can hold at various points in a program, determining how those values propagate through the program, and where they are used. In CodeQL, you can model both local data flow and global data flow. For more background information, see :doc:`Introduction to data flow analysis with CodeQL <../intro-to-data-flow>`.
+Data flow analysis computes the possible values that a variable can hold at various points in a program, determining how those values propagate through the program, and where they are used. In CodeQL, you can model both local data flow and global data flow. For a more general introduction to modeling data flow, see :doc:`About data flow analysis <../intro-to-data-flow>`.
 
 Local data flow
 ---------------

docs/language/learn-ql/csharp/dataflow.rst

@@ -9,7 +9,7 @@ About this article
 This article describes how data flow analysis is implemented in the CodeQL libraries for C# and includes examples to help you write your own data flow queries.
 The following sections describe how to use the libraries for local data flow, global data flow, and taint tracking.
 
-For a more general introduction to modeling data flow, see :doc:`Introduction to data flow analysis with CodeQL <../intro-to-data-flow>`.
+For a more general introduction to modeling data flow, see :doc:`About data flow analysis <../intro-to-data-flow>`.
 
 Local data flow
 ---------------

docs/language/learn-ql/intro-to-data-flow.rst

@@ -1,10 +1,11 @@
-Introduction to data flow analysis with CodeQL
-##############################################
+About data flow analysis
+########################
+
+Data flow analysis is used to compute the possible values that a variable can hold at various points in a program, determining how those values propagate through the program and where they are used. 
 
 Overview
 ********
 
-Data flow analysis computes the possible values that a variable can hold at various points in a program, determining how those values propagate through the program and where they are used. 
 Many CodeQL security queries implement data flow analysis, which can highlight the fate of potentially malicious or insecure data that can cause vulnerabilities in your code base.
 These queries help you understand if data is used in an insecure way, whether dangerous arguments are passed to functions, or whether sensitive data can leak.
 As well as highlighting potential security issues, you can also use data flow analysis to understand other aspects of how a program behaves, by finding, for example, uses of uninitialized variables and resource leaks.
@@ -23,7 +24,7 @@ See the following tutorials for more information about analyzing data flow in sp
 
     Note
 
-    Data flow analysis is used extensively in path queries. To learn more about path queries, see :doc:`Constructing path queries <writing-queries/path-queries>`.  
+    Data flow analysis is used extensively in path queries. To learn more about path queries, see :doc:`Creating path queries <writing-queries/path-queries>`.  
 
 .. _data-flow-graph:
 

docs/language/learn-ql/java/dataflow.rst

@@ -9,7 +9,7 @@ About this article
 This article describes how data flow analysis is implemented in the CodeQL libraries for Java and includes examples to help you write your own data flow queries.
 The following sections describe how to use the libraries for local data flow, global data flow, and taint tracking.
 
-For a more general introduction to modeling data flow, see :doc:`Introduction to data flow analysis with CodeQL <../intro-to-data-flow>`.
+For a more general introduction to modeling data flow, see :doc:`About data flow analysis <../intro-to-data-flow>`.
 
 Local data flow
 ---------------

docs/language/learn-ql/javascript/dataflow-cheat-sheet.rst

@@ -34,7 +34,7 @@ This query reports flow paths which:
 - Step through variables, function calls, properties, strings, arrays, promises, exceptions, and steps added by `isAdditionalTaintStep <https://help.semmle.com/qldoc/javascript/semmle/javascript/dataflow/TaintTracking.qll/predicate.TaintTracking$TaintTracking$Configuration$isAdditionalTaintStep.2.html>`__.
 - End at a node matched by `isSink <https://help.semmle.com/qldoc/javascript/semmle/javascript/dataflow/Configuration.qll/predicate.Configuration$Configuration$isSink.1.html>`__.
 
-See also: `Global data flow <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#global-data-flow>`__ and :doc:`Constructing path queries <../writing-queries/path-queries>`.
+See also: `Global data flow <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#global-data-flow>`__ and :doc:`Creating path queries <../writing-queries/path-queries>`.
 
 DataFlow module
 ---------------

docs/language/learn-ql/javascript/dataflow.rst

@@ -9,7 +9,7 @@ The various sections in this article describe how to utilize the libraries for l
 As our running example, we will develop a query that identifies command-line arguments that are passed as a file path to the standard Node.js ``readFile`` function.
 While this is not a problematic pattern as such, it is typical of the kind of reasoning that is frequently used in security queries.
 
-For a more general introduction to modeling data flow, see :doc:`Introduction to data flow analysis with CodeQL <../intro-to-data-flow>`.
+For a more general introduction to modeling data flow, see :doc:`About data flow analysis <../intro-to-data-flow>`.
 
 Data flow nodes
 ---------------

docs/language/learn-ql/locations.rst

@@ -1,10 +1,13 @@
-Locations and strings for QL entities
+Providing locations in CodeQL queries
 =====================================
 
 .. Not sure how much of this topic needs to change, and what the title should be
 
-Providing locations
--------------------
+CodeQL includes mechanisms for extracting the ___location of elements in a codebase. Use these mechanisms when writing custom CodeQL queries and libraries to help display information to users.
+
+
+About locations
+---------------
 
 When displaying information to the user, LGTM needs to be able to extract ___location information from the results of a query. In order to do this, all QL classes which can provide ___location information should do this by using one of the following mechanisms:
 

docs/language/learn-ql/ql-training.rst

@@ -62,4 +62,4 @@ More resources
 
 - If you are completely new to CodeQL, look at our introductory topics in :doc:`Learning CodeQL <index>`.
 - To find more detailed information about how to write queries for specific languages, visit the links in :ref:`Writing CodeQL queries <writing-ql-queries>`.
-- To see examples of CodeQL queries that have been used to find security vulnerabilities and bugs in open-source software projects, visit the `GitHub Security Lab website <https://securitylab.github.com/research>`__ and the associated `repository <https://github.com/github/security-lab>`__.
+- To see examples of CodeQL queries that have been used to find security vulnerabilities and bugs in open source software projects, visit the `GitHub Security Lab website <https://securitylab.github.com/research>`__ and the associated `repository <https://github.com/github/security-lab>`__.

docs/language/learn-ql/writing-queries/debugging-queries.rst

@@ -1,5 +1,10 @@
-Query writing: common performance issues
-========================================
+Troubleshooting query performance
+=================================
+
+Improve the performance of your CodeQL queries by following a few simple guidelines.
+
+About query performance
+-----------------------
 
 This topic offers some simple tips on how to avoid common problems that can affect the performance of your queries.
 Before reading the tips below, it is worth reiterating a few important points about CodeQL and the QL language:
@@ -19,9 +24,7 @@ Eliminate cartesian products
 The performance of a predicate can often be judged by considering roughly how many results it has. 
 One way of creating badly performing predicates is by using two variables without relating them in any way, or only relating them using a negation.
 This leads to computing the `Cartesian product <https://en.wikipedia.org/wiki/Cartesian_product>`__ between the sets of possible values for each variable, potentially generating a huge table of results.
-
 This can occur if you don't specify restrictions on your variables. 
-
 For instance, consider the following predicate that checks whether a Java method ``m`` may access a field ``f``::
 
    predicate mayAccess(Method m, Field f) {

docs/language/learn-ql/writing-queries/introduction-to-queries.rst

@@ -1,10 +1,12 @@
-Introduction to query files
-###########################
+About CodeQL queries
+####################
+
+CodeQL queries are used to analyze code for issues related to security, correctness, maintainability, and readability. 
 
 Overview
 ********
 
-Queries are programs written with CodeQL. They are designed to highlight issues related to the security, correctness, maintainability, and readability of a code base. You can also write custom queries to find specific issues relevant to your own project. Three important types of query are:
+CodeQL includes queries to find the most relevant and interesting problems for each supported language. You can also write custom queries to find specific issues relevant to your own project. The important types of query are:
 
 - **Alert queries**: queries that highlight issues in specific locations in your code.
 - **Path queries**: queries that describe the flow of information between a source and a sink in your code.
@@ -21,9 +23,8 @@ You can add custom queries to `custom query packs <https://lgtm.com/help/lgtm/ab
     You can explore the paths generated by path queries `directly in LGTM <https://lgtm.com/help/lgtm/exploring-data-flow-paths>`__ and in the `Results view <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__ in VS Code.
 
 
-This topic is a basic introduction to structuring query files. You can find further information on writing queries for specific programming languages `here <https://help.semmle.com/QL/learn-ql/>`__, and detailed technical information about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and the `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
-For information on how to format your code when contributing queries to the GitHub repository, see the `CodeQL style guide <https://github.com/Semmle/ql/blob/master/docs/ql-style-guide.md>`__.
-
+This topic is a basic introduction to query files. You can find more information on writing queries for specific programming languages `here <https://help.semmle.com/QL/learn-ql/>`__, and detailed technical information about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and the `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
+For more information on how to format your code when contributing queries to the GitHub repository, see the `CodeQL style guide <https://github.com/Semmle/ql/blob/master/docs/ql-style-guide.md>`__.
 
 Basic query structure
 *********************
@@ -44,7 +45,7 @@ Basic query structure
     where /* ... logical formula ... */
     select /* ... expressions ... */
 
-The following sections describe the information that is typically included in a query file for alerts and metrics. Path queries are discussed in more detail in :doc:`Constructing path queries <path-queries>`. 
+The following sections describe the information that is typically included in a query file for alerts and metrics. Path queries are discussed in more detail in :doc:`Creating path queries <path-queries>`. 
 
 Query metadata
 ==============
@@ -54,7 +55,7 @@ Query metadata is used to identify your custom queries when they are added to th
 - If you are contributing a query to the GitHub repository, please read the `query metadata style guide <https://github.com/Semmle/ql/blob/master/docs/query-metadata-style-guide.md#metadata-area>`__. 
 - If you are adding a custom query to a query pack for analysis using LGTM , see `Writing custom queries to include in LGTM analysis <https://lgtm.com/help/lgtm/writing-custom-queries>`__.
 - If you are analyzing a database using the `CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__, your query metadata must contain ``@kind``.
-- If you are running a query in the query console on LGTM or with the CodeQL extension for VS Code, metadata is not mandatory. However, if you want your results to be displayed as either an 'alert' or a 'path', you must specify the correct ``@kind`` property, as explained below. See `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__ and `Using the extension <https://help.semmle.com/codeql/codeql-for-vscode/procedures/using-extension.html>`__ for further information.
+- If you are running a query in the query console on LGTM or with the CodeQL extension for VS Code, metadata is not mandatory. However, if you want your results to be displayed as either an 'alert' or a 'path', you must specify the correct ``@kind`` property, as explained below. For more information, `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__ and `Using the extension <https://help.semmle.com/codeql/codeql-for-vscode/procedures/using-extension.html>`__.
 
 .. pull-quote:: 
 
@@ -78,20 +79,19 @@ When writing your own alert queries, you would typically import the standard lib
 
 - C/C++: ``cpp``
 - C#: ``csharp``
-- COBOL: ``cobol``
+- Go: ``go``
 - Java: ``java``
 - JavaScript/TypeScript: ``javascript``
 - Python: ``python``
 
-There are also libraries containing commonly used predicates, types, and other modules associated with different analyses, including data flow, control flow, and taint-tracking. In order to calculate path graphs, path queries require you to import a data flow library into the query file. See :doc:`Constructing path queries <path-queries>` for further information.
+There are also libraries containing commonly used predicates, types, and other modules associated with different analyses, including data flow, control flow, and taint-tracking. In order to calculate path graphs, path queries require you to import a data flow library into the query file. For more information, see :doc:`Creating path queries <path-queries>`.
 
 You can explore the contents of all the standard libraries in the `CodeQL library reference documentation <https://help.semmle.com/QL/ql-libraries.html>`__ or in the `GitHub repository <https://github.com/semmle/ql>`__.
 
-
 Optional CodeQL classes and predicates
 --------------------------------------
 
-You can customize your analysis by defining your own predicates and classes in the query. See `Defining a predicate <https://help.semmle.com/QL/ql-handbook/predicates.html#defining-a-predicate>`__ and `Defining a class <https://help.semmle.com/QL/ql-handbook/types.html#defining-a-class>`__ for further details. 
+You can customize your analysis by defining your own predicates and classes in the query. For further information, see `Defining a predicate <https://help.semmle.com/QL/ql-handbook/predicates.html#defining-a-predicate>`__ and `Defining a class <https://help.semmle.com/QL/ql-handbook/types.html#defining-a-class>`__. 
 
 From clause
 ===========
@@ -117,9 +117,9 @@ Select clauses for alert queries (``@kind problem``) consist of two 'columns', w
 - ``element``: a code element that is identified by the query, which defines where the alert is displayed.
 - ``string``: a message, which can also include links and placeholders, explaining why the alert was generated. 
 
-The alert message defined in the final column of the ``select`` statement can be developed to give more detail about the alert or path found by the query using links and placeholders. For further information, see :doc:`Defining 'select' statements <select-statement>`. 
+You can modify the alert message defined in the final column of the ``select`` statement to give more detail about the alert or path found by the query using links and placeholders. For further information, see :doc:`Defining the results of a query <select-statement>`. 
 
-Select clauses for path queries (``@kind path-problem``) are crafted to display both an alert and the source and sink of an associated path graph. See :doc:`Constructing path queries <path-queries>` for further information.
+Select clauses for path queries (``@kind path-problem``) are crafted to display both an alert and the source and sink of an associated path graph. For more information, see :doc:`Creating path queries <path-queries>`.
 
 Select clauses for metric queries (``@kind metric``) consist of two 'columns', with the following structure::
 
@@ -128,16 +128,34 @@ Select clauses for metric queries (``@kind metric``) consist of two 'columns', w
 - ``element``: a code element that is identified by the query, which defines where the alert is displayed.
 - ``metric``: the result of the metric that the query computes.
 
+Viewing the standard CodeQL queries
+***********************************
+
+One of the easiest ways to get started writing your own queries is to modify an existing query. To view the standard CodeQL queries, or to try out other examples, visit the `CodeQL <https://github.com/semmle/ql>`__ and `CodeQL for Go <https://github.com/github/codeql-qo>`__ repositories on GitHub. 
+
+You can also find examples of queries developed to find security vulnerabilities and bugs in open source software projects on the `GitHub Security Lab website <https://securitylab.github.com/research>`__ and in the associated `repository <https://github.com/github/security-lab>`__.
+
+Contributing queries
+********************
+
+Contributions to the standard queries and libraries are very welcome. For more information, see our `contributing guidelines <https://github.com/Semmle/ql/blob/master/CONTRIBUTING.md>`__.
+If you are contributing a query to the open source GitHub repository, writing a custom query for LGTM, or using a custom query in an analysis with the CodeQL CLI, then you need to include extra metadata in your query to ensure that the query results are interpreted and displayed correctly. See the following topics for more information on query metadata:
+
+-  :doc:`Metadata for CodeQL queries <query-metadata>`
+-  `Query metadata style guide on GitHub <https://github.com/Semmle/ql/blob/master/docs/query-metadata-style-guide.md>`__
+
+Query contributions to the open source GitHub repository may also have an accompanying query help file to provide information about their purpose for other users. For more information on writing query help, see the `Query help style guide on GitHub <https://github.com/Semmle/ql/blob/master/docs/query-help-style-guide.md>`__ and the :doc:`Query help files <query-help>`.
+
 Query help files
 ****************
 
-When you write a custom query, we also recommend that you write a query help file to explain the purpose of the query to other users. For more information, see the `Query help style guide <https://github.com/Semmle/ql/blob/master/docs/query-help-style-guide.md>`__ on GitHub, and the :doc:`Query help reference <query-help>`. 
+When you write a custom query, we also recommend that you write a query help file to explain the purpose of the query to other users. For more information, see the `Query help style guide <https://github.com/Semmle/ql/blob/master/docs/query-help-style-guide.md>`__ on GitHub, and the :doc:`Query help files <query-help>`. 
 
 What next?
 ==========
 
 - See the queries used in real-life variant analysis on the `GitHub Security Lab website <https://securitylab.github.com/research>`__.
-- To learn more about writing path queries, see :doc:`Constructing path queries <path-queries>`.
+- To learn more about writing path queries, see :doc:`Creating path queries <path-queries>`.
 - Take a look at the `built-in queries <https://help.semmle.com/wiki/display/QL/Built-in+queries>`__ to see examples of the queries included in CodeQL.
 - Explore the `query cookbooks <https://help.semmle.com/wiki/display/QL/QL+cookbooks>`__ to see how to access the basic language elements contained in the CodeQL libraries.
 - For a full list of resources to help you learn CodeQL, including beginner tutorials and language-specific examples, visit `Learning CodeQL <https://help.semmle.com/QL/learn-ql/>`__.