Address technical review feedback

Author: felicitymay

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

@@ -143,12 +143,12 @@ 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
-......................
+Diagnostic and summary 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.
+The code scanning query suites include additional diagnostic and summary queries. When the database analysis is complete, the CLI generates the results file and reports any diagnostic and summary data to standard output. If you choose to generate SARIF output, the additional data is also included 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.
+If the analysis found fewer results for standard queries than you expected, review the results of the diagnostic and summary 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,10 @@ 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``),
-  a path (``@kind path-problem``), or a diagnostic metric (``@kind diagnostic``).
+- Query type (``@kind``): identifies the query as a simple alert (``@kind problem``),
+  an alert documented by a sequence of code locations (``@kind path-problem``), 
+  for extractor troubleshooting (``@kind diagnostic``), or a summary metric 
+  (``@kind metric`` and ``@tags summary``).
 
 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

@@ -57,9 +57,10 @@ 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``.
+    - Alert query metadata must contain ``@kind problem`` to identify the results as a simple alert.
+    - Path query metadata must contain ``@kind path-problem`` to identify the results as an alert documented by a sequence of code locations.
+    - Diagnostic query metadata must contain ``@kind diagnostic`` to identify the results as troubleshooting data about the extraction process.
+    - Summary query metadata must contain ``@kind metric`` and ``@tags summary`` to identify the results as summary metrics for the CodeQL database.
 
     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.
 
@@ -115,7 +116,7 @@ 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>`__.
+Select clauses for diagnostic queries (``@kind diagnostic``) and summary metric queries (``@kind metric`` and ``@tags summary``) have different requirements. For examples, see the `diagnostic queries <https://github.com/github/codeql/search?q=%22%40kind+diagnostic%22>`__ and the `summary metric queries <https://github.com/github/codeql/search?q=%22%40kind+metric%22+%22%40tags+summary%22>`__  in the CodeQL repository.
 
 Viewing the standard CodeQL queries
 ***********************************