update docs with directories info OD-183

docs/codacy-api/examples/obtaining-code-quality-metrics-for-files.md

@@ -2,9 +2,9 @@
 description: Example of how to obtain code quality metrics for files in a repository programmatically using the Codacy API endpoint listFiles.
 ---
 
-# Obtaining code quality metrics for files
+# Obtaining code quality metrics for files and directories
 
-To obtain the code quality information for your files in a flexible way, use the Codacy API endpoint [<span class="skip-vale">listFiles</span>](https://app.codacy.com/api/api-docs#listfiles).
+To obtain the code quality information for your files and directories in a flexible way, use the Codacy API endpoints [<span class="skip-vale">listFiles</span>](https://app.codacy.com/api/api-docs#listfiles), and [<span class="skip-vale">listDirectories</span>](https://app.codacy.com/api/api-docs#listDirectories).
 
 For example, if you're managing your source code using a monorepo strategy you may want to generate separate code quality reports for the subset of files that belong to each component or project in your repository.
 

docs/repositories/files.md

@@ -1,25 +1,38 @@
 # Files page
 
-The **Files page** displays the current code quality information for each analyzed file in your [enabled repository branches](../repositories-configure/managing-branches.md).
+The **Files page** displays the current code quality information for each analyzed file and folder in your [enabled repository branches](../repositories-configure/managing-branches.md).
 
-By default, the page lists the files on the main branch of your repository. However, if you have [more than one branch enabled](../repositories-configure/managing-branches.md), you can select other branches using the drop-down list at the top of the page.
+By default, the page lists the contents of the root directory on the main branch of your repository. However, if you have [more than one branch enabled](../repositories-configure/managing-branches.md), you can select other branches using the drop-down list at the top of the page.
 
-Codacy displays the following [code quality metrics](../faq/code-analysis/which-metrics-does-codacy-calculate.md) for each file, if available:
+## Browsing by folder
 
--   **Grade:** Overall grade of the file
--   **Issues:** Number of issues in the file
--   **Complexity:** Cyclomatic complexity of the file
--   **Duplication:** Number of duplicated code blocks in the file
--   **Coverage:** Percentage of coverable source lines of code that are covered by tests
+The Files page lets you browse your repository by directory. Folders are listed at the top of the table. Click a folder to drill into it and see its contents. Use the breadcrumb trail at the top of the table to navigate back up to any parent directory.
 
-Codacy displays the files in alphabetical order by default, but you can sort the list by each column to help you identify which files you should improve or refactor next.
+Each directory row shows the aggregated quality metrics for the current folder — across all files it contains, including files in nested subdirectories.
+
+![Directories](images/files-directories.png)
+
+!!! note
+    Directories are only available for repositories that have a completed analysis since 10th of July. If you don't see folders on the Files page, [reanalyze your repository](../faq/repositories/how-do-i-reanalyze-my-repository.md) to make them available.
+
+## Quality metrics
+
+Codacy displays the following [code quality metrics](../faq/code-analysis/which-metrics-does-codacy-calculate.md) for each file and folder, if available:
+
+-   **Grade:** Overall grade of the file or folder
+-   **Issues:** Number of issues in the file, or total issues across all files in the folder
+-   **Complexity:** Cyclomatic complexity of the file, or total complexity across all files in the folder
+-   **Duplication:** Number of duplicated code blocks in the file, or duplication percentage across all files in the folder
+-   **Coverage:** Percentage of coverable lines covered by tests in the file, or aggregated coverage percentage across all files in the folder
+
+The list is sorted with folders first and files below, both in alphabetical order by default. You can sort by any column to help you identify which directories or files to improve or refactor next.
 
 !!! note
-    You can [use the Codacy API to generate reports or obtain code quality metrics](../codacy-api/examples/obtaining-code-quality-metrics-for-files.md) for the files in your repositories in a more flexible way.
+    You can [use the Codacy API to generate reports or obtain code quality metrics](../codacy-api/examples/obtaining-code-quality-metrics-for-files.md) for the files and directories in your repositories in a more flexible way.
 
 ![Files list](images/files.png)
 
-Use the search box to filter the list and find specific files:
+Use the search box to filter the list and find specific files or folders:
 
 ![Finding specific files](images/files-search.png)