A few more updates

Author: felicitymay

docs/codeql/codeql-for-visual-studio-code/using-the-codeql-model-editor.rst

@@ -14,37 +14,46 @@ About the CodeQL model editor
 
 The CodeQL model editor guides you through modeling the calls to external dependencies in your application or fully modeling all the public entry and exit points in an external dependency
 
-When you open the model editor, it analyzes the currently selected CodeQL database and identifies where the application uses external APIs. An external (or third party) API is any API that is not part of the CodeQL database you have selected.
+When you open the model editor, it analyzes the currently selected CodeQL database and identifies where the application uses external APIs and all public methods. An external (or third party) API is any API that is not part of the CodeQL database you have selected.
 
 The model editor has two different modes:
 
-- Application mode (default view): The editor lists each the external framework used by the seelcted CodeQL database. When you expand a framework, a list of all calls to and from the external API is shown with the options available to model dataflow through each call. This mode is most useful for improving the CodeQL results for the specific codebase.
+- Application mode (default view): The editor lists each external framework used by the seelcted CodeQL database. When you expand a framework, a list of all calls to and from the external API is shown with the options available to model dataflow through each call. This mode is most useful for improving the CodeQL results for the specific codebase.
 
 - Dependency mode: The editor identifies the all publicly accessible APIs in the selected CodeQL database. This view guides you through modeling each public API that the codebase makes available. When you have finished modeling the entire API, you can save the model and use it to improve the CodeQL analysis for all codebases that use the dependency.
 
 Displaying the CodeQL model editor
 ----------------------------------
 
 #. Open your CodeQL workspace in VS Code, for example, the vscode-codeql-starter workspace.
-   If you haven't updated the `ql` submodule for a while, update it from `main` to ensure that you have the queries used to gather data for the model editor.
-#. Open the CodeQL extension and select the CodeQL database that you want to model from the Databases section of the left side pane.
+   If you haven't updated the ``ql`` submodule for a while, update it from ``main`` to ensure that you have the queries used to gather data for the model editor.
+#. Open the CodeQL extension and select the CodeQL database that you want to model from the "Databases" section of the left side pane.
 #. Use the command palette to run the “CodeQL: Open Model Editor (Beta)” command.
 #. The CodeQL model editor will open in a new tab and run a series of telemetry queries to identify APIs in the code.
 #. When the queries are complete, the APIs that have been identified are shown in the editor.
 
-Modeling the calls to external APIs from your codebase
-------------------------------------------------------
+Modeling the calls your codebase makes to external APIs
+-------------------------------------------------------
 
-You typically use this method when you are looking at a specific codebase where you want to improve the precision of CodeQL results. This is usually when the codebase uses frameworks or libraries that are not supported by CodeQL and they also are not used by other teams in your organization. 
+You typically use this method when you are looking at a specific codebase where you want to improve the precision of CodeQL results. This is usually when the codebase uses frameworks or libraries that are not supported by CodeQL but they are not used by other teams in your organization. 
 
 #. Select the CodeQL database that you want to improve CodeQL coverage for.
-#. Display the CodeQL model editor, by default the editor runs in application mode, so displays the list of external APIs used by the selected codebase.
-   INSERT SCREENSHOT?
+#. Display the CodeQL model editor, by default the editor runs in application mode, so the list of external APIs used by the selected codebase is shown.
+
+   .. image:: ../images/codeql-for-visual-studio-code/model-application-mode.png
+      :width: 800
+      :alt: Screenshot of the "Application mode" view of the CodeQL model pack editor in Visual Studio Code showing three of the external frameworks used by the "sofa-jraft" codebase.
 
 #. Click to expand an external API and view the list of calls from the codebase to the external dependency.
 #. Click **View** associated with an API call or method to show where it is used in your codebase.
+
+   .. image:: ../images/codeql-for-visual-studio-code/model-application-mode-expanded.png
+      :width: 800
+      :alt: Screenshot of the "Application mode" view of the CodeQL model pack editor in Visual Studio Code showing the calls to the "rocksdbjni" framework ready for modeling. The "View" option for the first call is highlighted with a dark orange outline.
+
 #. When you have determined how to model the call or method, define the **Model type**.
 #. The remaining fields are updated with available options:
+
    - **Source**: choose the **Output** element to model.
    - **Sink**: choose the **Input** element to model.
    - **Flow summary**: choose the **Input** and **Output** elements to model.
@@ -64,16 +73,25 @@ The models are stored in a series of YAML data extension files, one for each ext
 Modeling the public API of a codebase
 -------------------------------------
 
-You typically use this method when you want to model a framework or library that your organization uses in more than one codebase. Once you have finished creating and testing the model, you can publish the CodeQL model pack for your whole organization to use.
+You typically use this method when you want to model a framework or library that your organization uses in more than one codebase. Once you have finished creating and testing the model, you can publish the CodeQL model pack to the GitHub Container Registry for your whole organization to use.
 
 #. Select the CodeQL database that you want to model.
 #. Display the CodeQL model editor, by default the editor runs in application mode. Click **Model as dependency** to display dependency mode. The screen changes to show the public API of the framework or library.
-   INSERT SCREENSHOT?
 
-#. Click to expand a public method and view the list of available methods.
+   .. image:: ../images/codeql-for-visual-studio-code/model-dependency-mode.png
+      :width: 800
+      :alt: Screenshot of the "Dependency mode" view of the CodeQL model pack editor in Visual Studio Code showing three of the packages published by the "sofa-jraft" codebase.
+
+#. Click to expand a package and view the list of available methods.
 #. Click **View** associated with a method to show its definition.
+
+   .. image:: ../images/codeql-for-visual-studio-code/model-dependency-mode-expanded.png
+      :width: 800
+      :alt: Screenshot of the "Dependency mode" view of the CodeQL model pack editor in Visual Studio Code showing the public methods available in the "com.alipay.soft.jraft.option" package ready for modeling. The "View" option for the first method is highlighted with a dark orange outline.
+
 #. When you have determined how to model the method, define the **Model type**.
 #. The remaining fields are updated with available options:
+
    - **Source**: choose the **Output** element to model.
    - **Sink**: choose the **Input** element to model.
    - **Flow summary**: choose the **Input** and **Output** elements to model.
@@ -97,12 +115,10 @@ Testing CodeQL model packs
 
 You can test any CodeQL model packs you create in VS Code by toggling the "use model packs" setting on and off. This method works for both databases and for variant analysis repositories.
 
-- To run queries on a CodeQL database with any model packs that are stored within the ``.github/codeql/extensions`` directory of the workspace, update your ``settings.json`` file with: ``"codeQL.runningQueries.useModelPacks": all,``.
-- To run queries on a CodeQL database without using model packs, update your ``settings.json`` file with: ``"codeQL.runningQueries.useModelPacks": none,``.
-
-If your model is working well, you should see a difference in the results of the two different runs. If you don't see any differences results, you may want to introduce a known bug to verify that the model behaves as expected.
+- To run queries on a CodeQL database with any model packs that are stored within the ``.github/codeql/extensions`` directory of the workspace, update your ``settings.json`` file with: ``"codeQL.runningQueries.useModelPacks": all,``
+- To run queries on a CodeQL database without using model packs, update your ``settings.json`` file with: ``"codeQL.runningQueries.useModelPacks": none,``
 
-#. If you have set up VS Code to use data extensions (using the “codeQL.runningQueries.useExtensionPacks” setting), then you can also run a query and see that the unsafe calls are now detected.
+If your model is working well, you should see a difference in the results of the two different runs. If you don't see any differences in results, you may need to introduce a known bug to verify that the model behaves as expected.
 
 Using CodeQL model packs with code scanning
 -------------------------------------------

docs/codeql/codeql-for-visual-studio-code/working-with-codeql-packs-in-visual-studio-code.rst

@@ -52,8 +52,4 @@ To view the full definition of an element of a query, you can right-click and ch
 Working with CodeQL model packs
 -------------------------------
 
-The CodeQL extension for Visual Studio Code includes a dedicated editor for creating and editing model packs. 
-
-TODO a little more, but mostly about the general use, because editing will be in a new article.
-
-For headings use ~~~~~~~~ in this section
+The CodeQL extension for Visual Studio Code includes a dedicated editor for creating and editing model packs. For information on using the model editor, see ":ref:`Using the CodeQL model editor <using-the-codeql-model-editor>`."

docs/codeql/codeql-language-guides/data-extensions-to-model-java-dependencies.rst

@@ -12,7 +12,11 @@ You can use data extensions to model the methods and callables that control data
 About this article
 ------------------
 
-This article explains how data extensions interact with standard queries and the syntax used to define extensions. If you want to create your own data extensions, you should use the CodeQL model editor in the CodeQL extension for Visual Studio Code. For more information, see ":ref:`Using the CodeQL model editor <using-the-codeql-model-editor>`."
+This article contains reference material about how data extensions interact with standard queries and the syntax used to define extensions.
+
+If you want to create your own data extensions, you should use the CodeQL model editor in the CodeQL extension for Visual Studio Code. The model editor automatically guides you through the process of defining models, displaying the properties you need to define and the options available. You can save the resulting models as data extensions and use them without worrying about the syntax.
+
+For more information, see ":ref:`Using the CodeQL model editor <using-the-codeql-model-editor>`."
 
 About data extensions
 ---------------------

docs/codeql/codeql-language-guides/extensible-predicates.rst

@@ -13,7 +13,7 @@ You can use data extensions to model the methods and callables that control data
 About this article
 ------------------
 
-This reference article describes of each inputs to the extensible predicates, including access paths, kinds, and provenance.
+This reference article describes the available inputs for the extensible predicates, including access paths, kinds, and provenance.
 
 Sources, sinks, summaries, and neutrals are commonly known as models. These models support several shared arguments and a few model-specific arguments. The arguments populate a series of columns for each extensible predicate.