Apply suggestions from code review

Author: aeisenberg

docs/codeql/codeql-cli/about-codeql-packs.rst

@@ -258,10 +258,10 @@ databases. You may also wish to specify the ``tests`` property.
 For more information about running tests, see ":doc:`Testing custom queries
 <testing-custom-queries>`."
 
-.. _standard-ql-packs:
+.. _standard-codeql-packs:
 
 Examples of CodeQL packs in the CodeQL repository
----------------------------------------------~~~~
+-------------------------------------------------
 
 Each of the languages in the CodeQL repository has four main CodeQL packs:
 
@@ -292,6 +292,7 @@ Some extra notes on the following properties:
 - ``library``: Indicates that this is a library pack with no executable queries. It is only meant to be used as a dependency for other packs.
 - ``dbscheme`` and ``upgrades``: These properties are internal to the CodeQL CLI and should only be defined in the core QL pack for a language.
 
+.. _standard-codeql-query-packs:
 
 Core query pack
 ~~~~~~~~~~~~~~~

docs/codeql/codeql-cli/analyzing-databases-with-the-codeql-cli.rst

@@ -123,6 +123,14 @@ You can also run your own custom queries with the ``database analyze`` command.
 For more information about preparing your queries to use with the CodeQL CLI,
 see ":doc:`Using custom queries with the CodeQL CLI <using-custom-queries-with-the-codeql-cli>`."
 
+If you do not have the CodeQL repository checked out, you can execute the same queries by specifying the query pack name and the path to the queries::
+
+   codeql database analyze --download <javascript-database> codeql/javascript-queries:Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv
+
+Use the ``--download`` flag to download the query pack if it isn't yet available locally.
+
+.. _run-query-pack:
+
 Running a CodeQL pack
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -136,6 +144,40 @@ pack names and use the ``--download`` flag::
 The ``analyze`` command above runs the default suite from ``microsoft/coding-standards v1.0.0`` and the latest version of ``github/security-queries`` on the specified database.
 For further information about default suites, see ":ref:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`".
 
+Running all queries in a directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can run all the queries located in a directory by providing the directory
+path, rather than listing all the individual query files. Paths are searched
+recursively, so any queries contained in subfolders will also be executed.
+
+.. pull-quote::
+
+   Important
+
+   You should avoid specifying the root of a :ref:`core CodeQL query pack
+   <standard-codeql-query-packs>` when executing ``database analyze``
+   as it might contain some special queries that aren't designed to be used with
+   the command. Rather, :ref:`run the query pack <run-query-pack>` to include the
+   pack's default queries in the analysis, or run one of the
+   code scanning query suites.
+
+For example, to execute all Python queries contained in the ``Functions`` directory you would run::
+
+   codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
+
+If you do not have the CodeQL repository checked out, you can execute the same queries by specifying the query pack name and the path to the queries::
+
+   codeql database analyze --download <python-database> codeql/python-queries:Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
+
+Use the ``--download`` flag to download the query pack if it isn't yet available locally.
+
+When the analysis has finished, a SARIF results file is generated. Specifying ``--format=sarif-latest`` ensures
+that the results are formatted according to the most recent SARIF specification
+supported by CodeQL.
+
+.. _including-query-help-for-custom-codeql-queries-in-sarif-files:
+
 Running a subset of queries in a CodeQL pack
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -196,7 +238,7 @@ CodeQL query suites are ``.qls`` files that use directives to select queries to
 based on certain metadata properties. The standard CodeQL packs have metadata that specify
 the location of the query suites used by code scanning, so the CodeQL CLI knows where to find these
 suite files automatically, and you don't have to specify the full path on the command line.
-For more information, see ":ref:`About CodeQL packs <standard-ql-packs>`."
+For more information, see ":ref:`About CodeQL packs <standard-codeql-packs>`."
 
 The standard query suites are stored at the following paths in
 the CodeQL repository::
@@ -228,40 +270,6 @@ Integrating a CodeQL pack into a code scanning workflow in GitHub
 You can use CodeQL query packs in your code scanning setup. This allows you to select query packs published by various sources and use them to analyze your code.
 For more information, see "`Using CodeQL query packs in the CodeQL action <https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-codeql-query-packs/>`_" or "`Downloading and using CodeQL query packs in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system#downloading-and-using-codeql-query-packs>`_."
 
-
-Running all queries in a directory
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can run all the queries located in a directory by providing the directory
-path, rather than listing all the individual query files. Paths are searched
-recursively, so any queries contained in subfolders will also be executed.
-
-.. pull-quote::
-
-   Important
-
-   You shouldn't specify the root of a :doc:`CodeQL pack
-   <about-codeql-packs>` when executing ``database analyze``
-   as it contains some special queries that aren't designed to be used with
-   the command. Rather, to run a wide range of useful queries, run one of the
-   LGTM.com query suites.
-
-For example, to execute all Python queries contained in the ``Functions`` directory you would run::
-
-   codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
-
-If you do not have the CodeQL repository checked out, you can execute the same queries by specifying the query pack name and the path to the queries:
-
-   codeql database analyze --download <python-database> codeql/python-queries:Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
-
-Use the ``--download`` flag to download the query pack if it isn't yet available locally.
-
-After evaluating, a SARIF results file is generated. Specifying ``--format=sarif-latest`` ensures
-that the results are formatted according to the most recent SARIF specification
-supported by CodeQL.
-
-.. _including-query-help-for-custom-codeql-queries-in-sarif-files:
-
 Including query help for custom CodeQL queries in SARIF files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/codeql/codeql-cli/creating-and-working-with-codeql-packs.rst

@@ -34,14 +34,14 @@ You must specify:
 
 The ``codeql pack init`` command creates the directory structure and configuration files for a CodeQL pack. By default, the command creates a query pack. If you want to create a library pack, you must edit the ``qlpack.yml`` file to explicitly declare the file as a library pack by including the ``library:true`` property.
 
-Modifying an existing legacy CodeQL pack to create a CodeQL pack
-----------------------------------------------------------------
+Modifying an existing legacy QL pack to create a CodeQL pack
+------------------------------------------------------------
 
 If you already have a ``qlpack.yml`` file, you can edit it manually to convert it into a CodeQL pack.
 
 #. Edit the ``name`` property so that it matches the format ``<scope>/<name>``, where ``<scope>`` is the name of the GitHub organization or user account that you will publish to.
 #. In the ``qlpack.yml`` file, include a ``version`` property with a semver identifier, as well as an optional ``dependencies`` block.
-#. Migrate the list of dependencies in ``libraryPathDependencies`` to the ``dependencies`` block. Specify the version range for each dependency. If the range is unimportant, or you are unsure of compatibility, you can specify ``"*"``, which indicates that any version is acceptable and will default to the latest version when ``codeql pack install`` is run.
+#. Migrate the list of dependencies in ``libraryPathDependencies`` to the ``dependencies`` block. Specify the version range for each dependency. If the range is unimportant, or you are unsure of compatibility, you can specify ``"*"``, which indicates that any version is acceptable and will default to the latest version when you run ``codeql pack install``.
 
 For more information about the properties, see ":ref:`About CodeQL packs <about-codeql-packs>`."
 
@@ -53,7 +53,7 @@ You can add dependencies on CodeQL packs using the command ``codeql pack add``.
 
   codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>
 
-If you leave off the version range, the latest version will be added. Otherwise, the latest version that satisfies the requested range will be added.
+If you don't specify a version range, the latest version will be added. Otherwise, the latest version that satisfies the requested range will be added.
 
 This command updates the ``qlpack.yml`` file with the requested dependencies and downloads them into the package cache. Please note that this command will reformat the file and remove all comments.
 

docs/codeql/codeql-cli/creating-codeql-query-suites.rst

@@ -18,7 +18,7 @@ suite definition have been executed, the result is a set of selected queries.
 
 .. pull-quote:: Note
 
-   Any custom queries that you want to add to a query suite must be in a :doc:`QL
+   Any custom queries that you want to add to a query suite must be in a :doc:`CodeQL
    pack <about-codeql-packs>` and contain the correct query metadata.
    For more information, see
    ":doc:`Using custom queries with the CodeQL CLI <using-custom-queries-with-the-codeql-cli>`."
@@ -52,7 +52,7 @@ queries using:
      version: ^x.y.z
 
   The ``version`` field is optional and specifies a range of compatible versions of this CodeQL pack.
-  If the version is excluded, then the most recent version of the pack is used.
+  If you don't specify a version, then the most recent version of the pack is used.
 
 - A ``qlpack`` instruction---tells CodeQL to resolve queries in the default suite of the
   named CodeQL pack::
@@ -65,7 +65,7 @@ queries using:
   define a default suite, the `qlpack` instruction will resolve to all of the queries within the pack.
 
   The ``version`` field is optional and specifies a range of compatible versions of this CodeQL pack.
-  If the version is excluded, then the most recent version of the pack is used.
+  If you don't specify a version, then the most recent version of the pack is used.
 
 .. pull-quote:: Note
 
@@ -191,7 +191,7 @@ Existing query suite definitions can be reused by specifying:
       version: ^x.y.z
 
   The ``version`` field is optional and specifies a range of compatible versions of this CodeQL pack.
-  If the version is excluded, then the most recent version of the pack is used.
+  If you don't specify a version, then the most recent version of the pack is used.
 
   Queries added using an ``import`` instruction can be filtered using subsequent
   ``exclude`` instructions.