Merge pull request #14668 from github/shati-patel/docs-databases

VS Code extension docs: Changes to database downloads

Author: shati-patel

docs/codeql/codeql-for-visual-studio-code/customizing-settings.rst

@@ -39,7 +39,7 @@ Changing the labels of query history items
 
 The query history **Format** setting controls how the extension lists queries in the query history. By default, each item has a label with the following format::
     
-    %q on %d - %s, %r result count [%t]
+    %q on %d - %s %r [%t]
 
 - ``%q`` is the query name
 - ``%d`` is the database name
@@ -107,6 +107,19 @@ You can also edit the items shown in the Variant Analysis Repositories panel by
 
 You can change the items shown in the panel or add new items by directly editing this file.
 
+Configuring settings for adding databases
+------------------------------------------------
+
+To automatically add database source folders to your workspace, you can enable the **Adding Databases > Add Database Source to Workspace** setting.
+
+This setting is disabled by default. You may want to enable the setting if you regularly browse the source code of databases, for example to view the abstract syntax tree of the code. For more information, see ":ref:`Exploring the structure of your source code <exploring-the-structure-of-your-source-code>`."
+
+.. pull-quote:: Note
+
+   If you are in a single-folder workspace, adding database source folders will cause the workspace to reload as a multi-root workspace. This may cause query history and database lists to be reset.
+
+   Before enabling this setting, we recommend that you save your workspace as a multi-root workspace. For more information, see "`Multi-root Workspaces <https://code.visualstudio.com/docs/editor/multi-root-workspaces>`__" in the Visual Studio Code help.
+
 Configuring settings for testing queries locally
 ------------------------------------------------
 

docs/codeql/codeql-for-visual-studio-code/exploring-the-structure-of-your-source-code.rst

@@ -18,20 +18,26 @@ CodeQL for Visual Studio Code contains an AST viewer. The viewer consists of a g
 Viewing the abstract syntax tree of a source file
 --------------------------------------------------
 
-1. Open a source file from a CodeQL database. For example, you can navigate to a source file in the File Explorer.
+1. Open the CodeQL Databases view and right-click the database that you want to explore. Click **Add Database Source to Workspace**.
+
+   .. image:: ../images/codeql-for-visual-studio-code/add-database-source-to-workspace.png
+      :width: 350
+      :alt: Add database source to workspace
+
+2. Navigate to a CodeQL database's source file in the File Explorer.
 
    .. image:: ../images/codeql-for-visual-studio-code/open-source-file.png
       :width: 350
       :alt: Open a source file
 
-2. Run **CodeQL: View AST** from the Command Palette. This runs a CodeQL query (usually called ``printAST.ql``) over the active file, which may take a few seconds.
+3. Run **CodeQL: View AST** from the Command Palette. This runs a CodeQL query (usually called ``printAST.ql``) over the active file, which may take a few seconds.
 
    .. pull-quote:: Note
 
       If you don't have an appropriate ``printAST.ql`` query in your workspace, the **CodeQL: View AST** command won't work. To fix this, you can update your copy of the `CodeQL <https://github.com/github/codeql>`__ repository from ``main``. If you do this, you may need to upgrade your databases. Also, query caches may be discarded and your next query runs could be slower.
 
-3. Once the query has run, the AST viewer displays the structure of the source file.
-4. To see the nested structure, click the arrows and expand the nodes.
+4. Once the query has run, the AST viewer displays the structure of the source file.
+5. To see the nested structure, click the arrows and expand the nodes.
 
    .. image:: ../images/codeql-for-visual-studio-code/explore-ast.png
       :alt: Explore the AST