Apply suggestions from code review

Co-authored-by: Jeff Matthews <matthews.jeffery@gmail.com>

Author: dobooth

src/_data/toc/contributor-guide.yml

@@ -18,7 +18,7 @@ pages:
           url: /contributor-guide/pull-request-tests.html
           versionless: true
 
-        - label: Adding Code Inspections with PHPStorm plugin
+        - label: PHPStorm plugin code inspections
           url: /contributor-guide/phpstorm-code-inspections.html
           versionless: true
 

src/_data/toc/extension-best-practices.yml

@@ -42,7 +42,7 @@ pages:
         - label: Code inspection
           url: /ext-best-practices/phpstorm/code-inspection.html
 
-        - label: New Features
+        - label: New features
           url: /ext-best-practices/phpstorm/extra.html
 
         - label: Issue reporting

src/contributor-guide/phpstorm-code-inspections.md

@@ -1,14 +1,12 @@
 ---
 group: contributor-guide
-title: Adding Code Inspections with PHPStorm plugin
-redirect_from:
-- contributor-guide/phpstorm-code-inspections.html
+title: PHPStorm plugin code inspections
 ---
 
-The PHPStorm plugin is a tool created by the community to optimize routine coding operations and improve the {{site.data.var.ee}} development experience. The plugin is compatible with IntelliJ IDEA Ultimate and PhpStorm IDE. The functionality includes {{site.data.var.ee}} specific code generation shortcuts, code inspections, autocomplete functionality for configuration files, MFTF tests, and Requirejs.
+The PHPStorm plugin is a tool created by the community to optimize routine coding operations and improve the {{site.data.var.ee}} development experience. The plugin is compatible with the IntelliJ IDEA Ultimate and PhpStorm IDEs. The functionality includes {{site.data.var.ee}} specific code generation shortcuts, code inspections, autocomplete functionality for configuration files, MFTF tests, and RequireJS.
 
 See the [Code generation]({{site.baseurl}}/guides/v2.3/ext-best-practices/phpstorm/code-generation.html) topic for more information.
 
-The PHPStorm plugin includes shortcuts for Functional Testing, Require JS mapping, GraphQL, Plugin declaration inspection, code generation, and many more.
+The PHPStorm plugin includes shortcuts for functional testing, RequireJS mapping, GraphQL, plugin declaration inspection, code generation, and much more.
 
 See the [Adding Code Inspections]({{site.baseurl}}/guides/v2.3/ext-best-practices/phpstorm/inspections.html) topic for more information on static code analysis.

src/guides/v2.3/ext-best-practices/phpstorm/code-generation.md

@@ -5,18 +5,18 @@ functional_areas:
   - Standards
 ---
 
-The PHPStorm plugin enables features and functionality to assist developers in creating custom extensions.
+The PHPStorm plugin enables features and functionality to help you create custom extensions.
 
 ### XML file header
 
 The new include code template was added to the generated with the plugin XML files.
-To configure it go to the `Preferences -> Editor -> File and Code Templates -> Includes -> XML File Header`:
+To configure it, go to the `Preferences -> Editor -> File and Code Templates -> Includes -> XML File Header`:
 
 ![]({{site.baseurl}}/common/images/phpstorm/xml-file-header.png)
 
 #### Usage
 
-Any generated XML file will have this header, as for example:
+All generated XML files include the header, for example:
 
 ![]({{site.baseurl}}/common/images/phpstorm/xml-file-header-in-file.png)
 

src/guides/v2.3/ext-best-practices/phpstorm/extra.md

@@ -1,11 +1,11 @@
 ---
 group: extension-best-practices
-title: New Features
+title: New features
 functional_areas:
   - Standards
 ---
 
-Best practices for several issues within the PHPStorm plugin.
+The following sections describe best practices for using the PHPStorm plugin.
 
 ### JS and CSS support for Copy Magento Path action
 

src/guides/v2.3/ext-best-practices/phpstorm/inspections.md

@@ -1,22 +1,23 @@
 ---
 group: extension-best-practices
-title: Adding Code Inspections
+title: Adding code inspections
 functional_areas:
   - Standards
 ---
 
-The IntelliJ Platform provides tools designed for static code analysis called code inspections, which help the user maintain and clean up code without actually executing it.
+The IntelliJ Platform provides tools designed for static code analysis called code inspections, which help you maintain and clean up code without actually executing it.
 Read more in the [official documentation](https://plugins.jetbrains.com/docs/intellij/code-inspections.html).
 
-The plugin inspections could be found in the `Settings | Preferences... | Editor | Inspections`.
+you can find plugin inspections  in `Settings | Preferences... | Editor | Inspections`.
 Use a filter to find only the plugin inspections: `Magento 2`.
 
 ![Image of the Magento 2 Group Inspections]({{site.baseurl}}/common/images/phpstorm/Intellij-idea-plugin-editor-local-inspections.png)
 
 See [Inspections topic](https://jetbrains.design/intellij/text/inspections/) in the IntelliJ Platform UI Guidelines
-on naming, writing description, and message texts for inspections to avoid basic naming conventions issues before code review.
+for naming, writing descriptions, and messages for inspections to avoid basic naming convention issues before code review.
 
 ### To add a new inspection
+Adding a new code inspection includes:
 
 1. Declaring an inspection in the plugin configuration file
 1. Implementing a local inspection class to inspect code in the IntelliJ Platform-based IDE editor
@@ -28,7 +29,7 @@ on naming, writing description, and message texts for inspections to avoid basic
 
 ### Declaring an inspection in the plugin configuration file
 
-All plugin inspections declared in the `<extensions defaultExtensionNs="com.intellij">` XML node of the plugin configuration file.
+You must declare all plugin inspections in the `<extensions defaultExtensionNs="com.intellij">` XML node of the plugin configuration file.
 
 For example, we will implement a local inspection tool for checking preference XML tag attributes (`di.xml` file)
 if they are valid classes FQNs.
@@ -113,9 +114,9 @@ All visitors should extend `com.intellij.psi.PsiElementVisitor`.
 | `JSON` | `com.intellij.json.psi.JsonElementVisitor` |
 | `JavaScript` | `com.intellij.psi.PsiElementVisitor` |
 
-Let's implement new `XmlElementVisitor` that overrides `visitXmlTag` method. That visitor will check all xml tags
-in the all xml files. We should dedicate it to check only expected xml files (`di.xml`) and expected xml tags (`<type/>`).
-That could be easily be done with the next part of code:
+Let's implement new `XmlElementVisitor` that overrides `visitXmlTag` method. That visitor will check all XML tags
+in all XML files. We should dedicate it to check only expected XML files (`di.xml`) and expected XML tags (`<type/>`).
+Use the following code to check only expected XML files:
 
 ```java
 final PsiFile file = xmlTag.getContainingFile();
@@ -126,24 +127,24 @@ if (!file.getName().equals(ModuleDiXml.FILE_NAME)
 }
 ```
 
-Now we can access `<type/>` tag's `name` attribute to check its value:
+Now we can access the `<type/>` tag's `name` attribute to check its value:
 
 ```java
 final XmlAttribute nameAttribute = xmlTag.getAttribute(ModuleDiXml.NAME_ATTR);
 ```
 
 The `XmlTag.getAttribute()` method returns `@Nullable` value. We should check if our attribute is accessible for working with it.
-Also, later we will need to use `XmlTag.getValueElement()` method to register problem by `ProblemsHolder` if it occurs.
-The `XmlTag.getValueElement()` method also returns `@Nullable` value. Let's use this code to skip visiting not correct XML attributes:
+Also, later we will need to use the `XmlTag.getValueElement()` method to register problems using `ProblemsHolder` if they occur.
+The `XmlTag.getValueElement()` method also returns `@Nullable` value. Let's use this code to skip checking incorrect XML attributes:
 
 ```java
 if (nameAttribute == null || nameAttribute.getValue() == null || nameAttribute.getValueElement() == null) {
     return;
 }
 ```
 
-Now we can access attributes values. We can check if attribute value is existing class by using [PhpClassExistenceValidator] type instance.
-To report problem on the `name` attribute value you can use the next code snippet:
+Now we can access attribute values. We can check if an attribute value is an existing class by using the [PhpClassExistenceValidator] type instance.
+To report problem with the `name` attribute value, you can use the following code:
 
 ```java
 problemsHolder.registerProblem(
@@ -156,24 +157,27 @@ problemsHolder.registerProblem(
 );
 ```
 
-You cannot access tag value of PsiElement type.
-So you can just report problem for tag element, as it is done by Intellij Idea inspections, for example: `com.intellij.xml.util.CheckEmptyTagInspection`.
+You cannot access the tag value of the `PsiElement` type.
+You should report problems with the tag element similar to Intellij Idea inspections. For example: `com.intellij.xml.util.CheckEmptyTagInspection`.
 
 So, there is a full example: [InvalidDependencyInjectionTypeInspection]
 
-### Writing an HTML description of the inspection for display in the inspection preferences panel
+### Writing HTML descriptions
 
-You must describe all inspections in the description file. To do this you can add a new HTML file by the next path:
+This section shows you how to display an HTML description of the inspection in the inspection preferences panel.
+
+
+You must describe all inspections in the description file. To do this, you can add a new HTML file to the following path:
 `./resources/inspectionDescriptions/{shortName}.html`, where `{shortName}` is a `shortName` attribute value in the
-local inspection declaration. Or you can just use Intellij Idea automation for this (preferred way ).
-All inspection implementation classes have highlighted class name if they don't have description file and quick fix to create it:
+local inspection declaration. Or you can just use Intellij Idea automation to do this (preferred).
+All inspection implementation classes have highlighted class names if they don't have description files. Here's a quick fix to create it:
 ![Create Inspection Description File Quick Fix]({{site.baseurl}}/common/images/phpstorm/Intellij-idea-plugin-create-inspection-description-quick-fix.png)
 
 Use [Inspections topic](https://jetbrains.design/intellij/text/inspections/) to write better descriptions for inspections using naming conventions.
 
 ### Create a unit test for the inspection
 
-You must deliver each inspection with the unit test for it. The root folder for all inspections unit tests is a `./tests/com/magento/idea/magento2plugin/inspections`. As base classes for your tests you should use predefined implementations based on languages.
+You must deliver each inspection with the unit test for it. The root folder for all inspections unit tests is `./tests/com/magento/idea/magento2plugin/inspections`. As base classes for your tests you should use predefined implementations based on languages.
 
 **Base classes implementations for different languages:**
 
@@ -183,8 +187,8 @@ You must deliver each inspection with the unit test for it. The root folder for
 | `xml` | `com.magento.idea.magento2plugin.inspections.xml.InspectionXmlFixtureTestCase` |
 | `graphql` | `com.magento.idea.magento2plugin.inspections.graphqls.InspectionGraphqlsFixtureTestCase` |
 
-If you cover new language area, please extend `com.magento.idea.magento2plugin.inspections.BaseInspectionsTestCase` class and add new abstract class for that area.
-All test classes names should have a suffix Test and all testing methods should have a prefix test and detailed description in the annotation.
+If you cover new language area, please extend the `com.magento.idea.magento2plugin.inspections.BaseInspectionsTestCase` class and add a new abstract class for that area.
+All test class names should have the suffix "test" and all testing methods should have the prefix "test" and detailed description in the annotation.
 Also, you should enable testing inspection in the `setUp()` method.
 
 ```java

src/guides/v2.3/ext-best-practices/phpstorm/introduction.md

@@ -1,11 +1,11 @@
 ---
 group: extension-best-practices
-title: PHPStorm Plugin
+title: PHPStorm plugin
 functional_areas:
   - Standards
 ---
 
-The PHPStorm plugin is a tool created by the community to optimize routine coding operations and improve the {{site.data.var.ee}} development experience. The plugin is compatible with IntelliJ IDEA Ultimate and PhpStorm IDE. The functionality includes {{site.data.var.ee}} specific code generation shortcuts, code inspections, autocomplete functionality for configuration files, MFTF tests, and Requirejs.
+The PHPStorm plugin is a tool created by the community to optimize routine coding operations and improve the {{site.data.var.ee}} development experience. The plugin is compatible with the IntelliJ IDEA Ultimate and PhpStorm IDEs. The functionality includes {{site.data.var.ee}} specific code generation shortcuts, code inspections, autocomplete functionality for configuration files, MFTF tests, and RequireJS.
 
 See the [Code generation]({{site.baseurl}}/guides/v2.3/ext-best-practices/phpstorm/code-generation.html) topic for more information.
 

src/guides/v2.3/ext-best-practices/phpstorm/uct-run-configuration.md

@@ -11,14 +11,14 @@ Run Configurations are used to run internal and external processes from within I
 
 See the [Run/Debug configurations topic](https://www.jetbrains.com/help/idea/run-debug-configuration.html) in the IntelliJ IDEA to understand the concept of a run configuration.
 
-The Run Configuration is a Graphical User Interface (GUI) for the {{site.data.var.uct}}. This allows the {{site.data.var.uct}} instance to be configured via composer. It is recommended that the {{site.data.var.uct}} is installed in the current project. However, if the {{site.data.var.uct}} is located outside the current project, a message is shown alerting of the possibility to download and install {{site.data.var.uct}} in the current project.
+The Run Configuration is a Graphical User Interface (GUI) for the {{site.data.var.uct}}. This allows the {{site.data.var.uct}} instance to be configured using Composer. We recommend that you install the {{site.data.var.uct}} in the current project. However, if the {{site.data.var.uct}} is located outside the current project, a message displays providing an optoin to download and install it in the current project.
 
 {:.bs-callout-warning}
-The {{site.data.var.uct}} is an {{site.data.var.ee}} feature. You will need your {{site.data.var.ee}} license key to install it.
+The {{site.data.var.uct}} is an {{site.data.var.ee}} feature. You need your {{site.data.var.ee}} license key to install it.
 
 ![]({{site.baseurl}}/common/images/phpstorm/uct-run-configuration-1-min.gif)
 
-When you create a new run configuration for a specific tool, create it from one of the dedicated configuration templates, which implement the startup logic, defines the list of parameters and their default values.
+When you create a new run configuration for a specific tool, create it from one of the dedicated configuration templates. Templates implement the startup logic and define the list of parameters and their default values.
 
 The {{site.data.var.uct}} Run Configuration template is located in the PHPStorm plugin menu, under **Run/Debug configurations** > **Add New Configuration** > **Upgrade Compatibility Tool**.
 
@@ -39,7 +39,7 @@ These are the main components of the {{site.data.var.uct}} Run Configuration tem
 
 See [Run]({{site.baseurl}}/upgrade-compatibility-tool/run.html) topic for more information on these specific options of the {{site.data.var.uct}}.
 
-Once the template is configured correctly, you can run the {{site.data.var.uct}} via a single click in your Run Configuration GUI.
+After you correctly configure the template, you can run the {{site.data.var.uct}} with a single click in your Run Configuration GUI.
 
 ## Run the tool