Draft docs for revised UI

Author: felicitymay

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

@@ -18,7 +18,7 @@ When you open the model editor, it analyzes the currently selected CodeQL databa
 
 The model editor has two different modes:
 
-- Application mode (default view): The editor lists each external framework used by the selected 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 selected 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 a specific codebase.
 
 - Dependency mode: The editor identifies all of the 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.
 
@@ -28,38 +28,49 @@ 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.
-#. 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.
+#. In the left side panel, expand the "CodeQL method modeling" section and click **Start modeling** to display the model editor.
+#. The CodeQL model editor runs a series of telemetry queries to identify APIs in the code and opens in a new tab.
 #. When the queries are complete, the APIs that have been identified are shown in the editor.
 
 Modeling the calls your codebase makes to external APIs
 -------------------------------------------------------
 
-You typically use this approach 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 if the source code of the framework or library is not included in the analysis.
+You typically use this approach when you are looking at a specific codebase where you want to improve the precision of CodeQL results. This is useful when the codebase uses frameworks or libraries that are not supported by CodeQL and if the source code of the framework or library is not included in the analysis.
 
 #. 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 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.
+      :alt: Screenshot of the "Application mode" view of the CodeQL model pack editor in Visual Studio Code showing two of the external Java 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**.
+#. 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-view-code.png
+      :width: 800
+      :alt: Screenshot of a file showing a place where your codebase calls the API is highlighted with a dark orange outline.
+
+#. The file containing the first call from your codebase to the API is opened and a "CodeQL methods usage" view opened (typically this is co-located with the "Problems" and "Terminal" views. The "CodeQL methods usage" view lists of all the calls from your code to the API, grouped by method. You can click through each use to decide how to a model the method.
+
+   .. image:: ../images/codeql-for-visual-studio-code/model-application-mode-view-list.png
+      :width: 800
+      :alt: Screenshot of the "CodeQL methods usage" view. The currently displayed method call is highlighted blue.
+
+#. When you have determined how to model the call or method, define the **Model type** in either the main model editor tab, or in the "CodeQL method modeling" tab.
 #. 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.
 
 #. Define the **Kind** of dataflow for the model.
-#. When you have finished modeling, click **Save all** or **Save** (shown at the bottom right of each expanded list of calls). The percentage of calls modeled in the editor is updated.
+#. When you have finished modeling, display the main model editor and click **Save all** or **Save** (shown at the bottom right of each expanded list of methods). The percentage of methods modeled in the editor is updated.
 
 The models are stored in your workspace at ``.github/codeql/extensions/<codeql-model-pack>``, where ``<codeql-model-pack>`` is the name of the CodeQL database that you selected. That is, the name of the repository, hyphen, the language analyzed by CodeQL.
 
@@ -114,6 +125,15 @@ The models are stored in a series of YAML data extension files, one for each pub
 
 The editor will create a separate model file for each package that you model.
 
+Modeling methods that can be called in different ways
+-----------------------------------------------------
+
+Some methods behave differently according to how they are called. In this case, once you have created one model for the method, you can add a second model using the **+** button in the method row.
+
+   .. image:: ../images/codeql-for-visual-studio-code/model-dependency-mode-plus.png
+      :width: 800
+      :alt: Screenshot of the "Dependency mode" view of the CodeQL model pack editor in Visual Studio Code showing one model for the ``com.alipay.sofa.jraft.option.BallotBoxOptions.getClosureQueue()`` method. The "+" button is outlined in dark orange. Click this button to create a second model for the method.
+
 Testing CodeQL model packs
 --------------------------