Make minimal changes to CodeQL docs

Author: felicitymay

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

@@ -24,11 +24,12 @@ Before starting an analysis you must:
 Running ``codeql database analyze``
 ------------------------------------
 
-When you run ``database analyze``, it does two things:
+When you run ``database analyze``, it:
 
 #. Executes one or more query files, by running them over a CodeQL database.
 #. Interprets the results, based on certain query metadata, so that alerts can be
    displayed in the correct location in the source code.
+#. Reports the results of any diagnostic queries to standard output.
 
 You can analyze a database by running the following command::
 
@@ -142,6 +143,13 @@ These are stored alongside the code scanning suites with names of the form: ``<l
 For information about creating custom query suites, see ":doc:`Creating
 CodeQL query suites <creating-codeql-query-suites>`."
 
+Diagnostic information
+......................
+
+The code scanning query suites include additional diagnostic queries. When the database analysis is complete, the CLI generates the results file and reports any diagnostic data to standard output. If you choose to generate SARIF output, the diagnostic data is also included as `notification objects <https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317894>`__ in the SARIF file.
+
+If the analysis found fewer results for standard queries than you expected, review the results of the diagnostic queries to check whether the CodeQL database is likely to be a good representation of the codebase that you want to analyze.
+
 Running all queries in a directory
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/codeql/codeql-cli/using-custom-queries-with-the-codeql-cli.rst

@@ -33,8 +33,8 @@ following two properties to ensure that the results are interpreted correctly:
 
 - Query identifier (``@id``): a sequence of words composed of lowercase letters or
   digits, delimited by ``/`` or ``-``, identifying and classifying the query. 
-- Query type (``@kind``): identifies the query is an alert (``@kind problem``)
-  or a path (``@kind path-problem``).
+- Query type (``@kind``): identifies the query is an alert (``@kind problem``),
+  a path (``@kind path-problem``), or a diagnostic metric (``@kind diagnostic``).
 
 For more information about these metadata properties, see ":ref:`Metadata for CodeQL queries
 <metadata-for-codeql-queries>`" and the `Query metadata style guide

docs/codeql/writing-codeql-queries/about-codeql-queries.rst

@@ -58,6 +58,7 @@ Query metadata is used to identify your custom queries when they are added to th
     Queries that are contributed to the open source repository, added to a query pack in LGTM, or used to analyze a database with the :ref:`CodeQL CLI <codeql-cli>` must have a query type (``@kind``) specified. The ``@kind`` property indicates how to interpret and display the results of the query analysis:
 
     - Alert query metadata must contain ``@kind problem``.
+    - Diagnostic query metadata must contain ``@kind diagnostic``.
     - Path query metadata must contain ``@kind path-problem``.
 
     When you define the ``@kind`` property of a custom query you must also ensure that the rest of your query has the correct structure in order to be valid, as described below.
@@ -114,6 +115,8 @@ You can modify the alert message defined in the final column of the ``select`` s
 
 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 <creating-path-queries>`."
 
+Select clauses for diagnostic queries (``@kind diagnostic``) have different requirements. For examples, see the `diagnostic queries in the CodeQL repository <https://github.com/github/codeql/search?q=%22%40kind+diagnostic%22>`__.
+
 Viewing the standard CodeQL queries
 ***********************************