Improve documentation and comments (#2785)

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 We appreciate that. Do keep the following in mind: 
 
-* Before making significant contribution consider discussing the outline of 
+* Before making a significant contribution, consider discussing the outline of 
   your solution first. This may avoid a duplication of efforts.
 * When you send a [pull requests](https://help.github.com/articles/using-pull-requests), 
   please include tests to go along with it.
@@ -25,7 +25,7 @@ When building the project for the first time, run:
 The `cucumber-archetype` modules integration tests against `-SNAPSHOT` 
 versions of Cucumber. These must be installed first.
 
-Afterwards `./mvnw test` or `./mvnw verify` should work as expected.
+Afterward `./mvnw test` or `./mvnw verify` should work as expected.
 
 ## Formatting Java
 

README.md

@@ -22,7 +22,7 @@ Cucumber-JVM also integrates with all the popular
 
 ## Upgrading?
 
-Migration instructions from previous major version and a long form
+Migration instructions from previous major versions and a long form
 explanation of noteworthy changes can be found in the [release-notes archive](release-notes)
 
 The changes for the current major version can be found in the [CHANGELOG.md](CHANGELOG.md).

cucumber-bom/README.md

@@ -1,7 +1,7 @@
 # Bill of Materials
 
 It is fairly common for one project to use more than one Cucumber dependency. To
-keep these version in sync a Bill of Materials can be used.
+keep these versions in sync, a Bill of Materials can be used.
 
 ## Usage
 

cucumber-cdi2/README.md

@@ -1,8 +1,8 @@
 Cucumber CDI 2
 ==============
 
-Use CDI Standalone Edition (CDI SE) API to provide dependency injection in to
-steps definitions
+Use CDI Standalone Edition (CDI SE) API to provide dependency injection into
+steps definitions.
 
 Add the `cucumber-cdi2` dependency to your pom.xml:
 
@@ -48,7 +48,7 @@ And for Weld it is:
 
 ## Usage
 
-For each scenario a new CDI container is started. If not present in the
+For each scenario, a new CDI container is started. If not present in the
 container, step definitions are added as unmanaged beans and dependencies are
 injected.
 

cucumber-core/README.md

@@ -4,7 +4,7 @@ Cucumber Core
 Provides components needed to discover, parse and execute feature files. The
 core is designed with a few extension systems and plugin points. You
 typically don't depend directly on `cucumber-core` but rather use the different
-submodules together e.g. `cucumber-junit` and `cucumber-java`.     
+submodules together e.g. `cucumber-junit` and `cucumber-java`.
 
 ## Properties, Environment variables, System Options ##
 
@@ -79,7 +79,7 @@ Each property also has an `UPPER_CASE` and `snake_case` variant. For example
 ## Backend ##
 
 Backends consist of two components: a `Backend`, and an optional `ObjectFactory`.
-They are  respectively responsible for discovering glue classes, registering
+They are respectively responsible for discovering glue classes, registering
 step definitions, and creating instances of said glue classes. Backend and
 object factory implementations are discovered via SPI.
 
@@ -96,13 +96,13 @@ An event has a UUID. The UUID generator can be configured using the `cucumber.uu
 | io.cucumber.core.eventbus.RandomUuidGenerator       | Thread-safe, collision-free, multi-jvm  | ~1                                 | Reports may be generated on different JVMs at the same time. A typical example would be one suite that tests against Firefox and another against Safari. The exact browser is configured through a property. These are then executed concurrently on different Gitlab runners. |
 | io.cucumber.core.eventbus.IncrementingUuidGenerator | Thread-safe, collision-free, single-jvm | ~130                               | Reports are generated on a single JVM                                                                                                                                                                                                                                          |
 
-The performance gain on real project depend on the feature size.
+The performance gain on real projects depends on the feature size.
 
 When not specified, the `RandomUuidGenerator` is used.
 
 ## Plugin ##
 
-By implementing the Plugin interface classes can listen to execution events
+By implementing the Plugin interface, classes can listen to execution events 
 inside Cucumber JVM. Consider using a Plugin when creating test execution reports.
 
 ## FileSystem ##

cucumber-core/pom.xml

@@ -194,8 +194,8 @@
                 <executions>
                     <execution>
                         <!-- the cucumber-* dependencies of cucumber-core are
-                             non-trivial. This ensures that we not forget to
-                             update all intermediate dependencies. For instance
+                             non-trivial. This ensures that we do not forget to
+                             update all intermediate dependencies. For instance,
                              when updating messages -->
                         <id>enforce-dependency-convergence</id>
                         <configuration>

cucumber-core/src/main/java/io/cucumber/core/options/PluginOption.java

@@ -125,7 +125,7 @@ private static Class<? extends Plugin> parsePluginName(String pluginSpecificatio
             throw createPluginIsNotCompatible(pluginSpecification);
         }
 
-        // Replace IDEA plugin with TeamCity
+        // Replace IntelliJ IDEA plugin with TeamCity
         if (INCOMPATIBLE_INTELLIJ_IDEA_PLUGIN_CLASSES.contains(pluginName)) {
             log.debug(() -> "Incompatible IntelliJ IDEA Plugin detected. Falling back to teamcity plugin");
             return TeamCityPlugin.class;

cucumber-core/src/main/java/io/cucumber/core/plugin/TeamCityPlugin.java

@@ -131,9 +131,10 @@ public class TeamCityPlugin implements EventListener {
 
     @SuppressWarnings("unused") // Used by PluginFactory
     public TeamCityPlugin() {
-        // This plugin prints markers for Team City and IDEA that allows them
-        // associate the output to specific test cases. Printing to system out
-        // - and potentially mixing with other formatters - is intentional.
+        // This plugin prints markers for Team City and IntelliJ IDEA that
+        // allows them to associate the output to specific test cases. Printing
+        // to system out - and potentially mixing with other formatters - is
+        // intentional.
         this(System.out);
     }
 

cucumber-deltaspike/README.md

@@ -4,7 +4,7 @@ Cucumber DeltaSpike
 This module relies on [DeltaSpike Container Control](https://deltaspike.apache.org/documentation/container-control.html) to start/stop supported CDI container.
 
 ## Setup
-Enable cdi support for your steps by adding a (empty) beans.xml into your classpath (src/main/resource/META-INF for normal classes or src/test/resources/META-INF for test classes):
+Enable cdi support for your steps by adding an (empty) beans.xml into your classpath (src/main/resource/META-INF for normal classes or src/test/resources/META-INF for test classes):
 
 ```xml
 <beans xmlns="http://java.sun.com/xml/ns/javaee"
@@ -16,7 +16,7 @@ Enable cdi support for your steps by adding a (empty) beans.xml into your classp
 </beans>
 ```
 
-To use DependencyInjection add `@Inject` to any field which should be managed by CDI, for more information see [JSR330](https://www.jcp.org/en/jsr/detail?id=330).
+To use dependency injection, add `@Inject` to any field which should be managed by CDI. For more information, see [JSR330](https://www.jcp.org/en/jsr/detail?id=330).
 
 ```java
 public class BellyStepdefs {
@@ -28,13 +28,13 @@ public class BellyStepdefs {
 }
 ```
 
-This ObjectFactory doesn't start or stop any [Scopes](https://docs.oracle.com/javaee/6/tutorial/doc/gjbbk.html), so all beans live inside the default scope (Dependent). Now cucumber requested a instance of your stepdefinitions for every step, which means cdi create a new instance for every step and for all injected fields. This behaviour makes it impossible to share a state inside a szenario.
+This object factory doesn't start or stop any [Scopes](https://docs.oracle.com/javaee/6/tutorial/doc/gjbbk.html), so all beans live inside the default scope (Dependent). Now Cucumber requested an instance of your step definitions for every step, which means cdi create a new instance for every step and for all injected fields. This behaviour makes it impossible to share a state inside a scenario.
 
-To bybass this, you must annotate your class(es) with `@javax.inject.Singleton`:
-1. on stepdefintions: now the ojectfactory will create only one instance include injected fields per scenario and both injected fields and stepdefinitions can be used to share state inside a scenario.
-2. on any other class: now the objectfactory will create a new instance of your stepdefinitions per step and stepdefinitions can not be used to share state inside a scenario, only the annotated classes can be used to share state inside a scenario
+To bypass this, you must annotate your class(es) with `@javax.inject.Singleton`:
+1. on destinations: now the object factory will create only one instance include injected fields per scenario, and both injected fields and step definitions can be used to share state inside a scenario.
+2. on any other class: now the object factory will create a new instance of your step definitions per step and step definitions can not be used to share state inside a scenario, only the annotated classes can be used to share state inside a scenario
 
-you can also combine both approaches.
+You can also combine both approaches.
 
 ```java
 @Singleton
@@ -46,9 +46,9 @@ public class BellyStepdefs {
     //normal step code ...
 }
 ```
-It is not possible to use any other scope than Dependent this means alsoi it is not possible to share a state over two or more scenarios, every scenario start with a clean environment.
+It is not possible to use any other scope than Dependent. This means also it is not possible to share a state over two or more scenarios; every scenario starts with a clean environment.
 
-To enable this objectfactory add the following dependency to your classpath:
+To enable this object factory, add the following dependency to your classpath:
 ```xml
 <dependency>
     <groupId>io.cucumber</groupId>
@@ -60,7 +60,7 @@ To enable this objectfactory add the following dependency to your classpath:
 
 and one of the supported cdi-containers.
 
-to use it with Weld:
+To use it with Weld:
 
 ```xml
 <dependency>
@@ -77,7 +77,7 @@ to use it with Weld:
 </dependency>
 ```
 
-or to use it with OpenEJB:
+To use it with OpenEJB:
 
 ```xml
 <dependency>
@@ -106,7 +106,8 @@ or to use it with OpenEJB:
 </dependency>
 ```
 
-or to use it with OpenWebBeans:
+To use it with OpenWebBeans:
+
 ```xml
 <dependency>
     <groupId>org.apache.deltaspike.cdictrl</groupId>
@@ -128,4 +129,4 @@ or to use it with OpenWebBeans:
 </dependency>
 ```
 
-Some containers need that you provide a CDI-API in a given version, but if you develop CDI and use one of the above containers it should already on your path.
+Some containers need you to provide a CDI-API in a given version, but if you develop CDI and use one of the above containers, it should already be on your path.

cucumber-guice/README.md

@@ -32,7 +32,7 @@ singleton and 'no scope'.
 
 ### Version 1.1.8 onwards
 A Guice injector is created once before any tests are run and is destroyed
-after the last test has run. Before each test scenario a new scenario scope
+after the last test has run. Before each test scenario, a new scenario scope
 is created. At the end of the test scenario the scenario scope is destroyed.
 Singleton scope exists throughout all test scenarios.
 
@@ -48,7 +48,7 @@ their singleton bindings updated. All bindings in
 By including the `cucumber-guice` jar on your
 `CLASSPATH` your Step Definitions will be instantiated by Guice.
 There are two main modes of using the module: with [scope annotations](#scoping-your-step-definitions) and with
-[module bindings](#using-module-bindings). The two modes can also be mixed. When mixing modes it is
+[module bindings](#using-module-bindings). The two modes can also be mixed. When mixing modes, it is
 important to realise that binding a class in a scope in a module takes
 precedence if the same class is also bound using a scope annotation.
 
@@ -78,7 +78,7 @@ be absolutely sure that a state change in one scenario could not possibly
 influence the success or failure of a subsequent scenario. As an example of
 when you might use a singleton, imagine you have an http client that is
 expensive to create. By holding a reference to the client in a class bound in
-singleton scope you can reuse the client in multiple scenarios.
+singleton scope, you can reuse the client in multiple scenarios.
 
 #### Using scope annotations
 This is the easy route if you're new to Guice. To bind a class in scenario
@@ -107,7 +107,7 @@ public class ScenarioScopedSteps {
 To bind a class in singleton scope add the
 `javax.inject.Singleton` annotation to the class definition. One
 strategy for using stateless step definitions is to use providers to share
-stateful scenario scoped instances between stateless singleton step
+stateful scenario-scoped instances between stateless singleton step
 definition instances. For example:
 
 ```java
@@ -136,7 +136,7 @@ There is an alternative explanation of using [providers for mixing scopes](https
 ### Using module bindings
 As an alternative to using annotations you may prefer to declare Guice
 bindings in a class that implements `com.google.inject.Module`. To
-do this you should create a class that implements
+do this, you should create a class that implements
 `io.cucumber.guice.api.InjectorSource`. This gives you complete
 control over how you obtain a Guice injector and it's Guice modules. The
 injector must provide a binding for

cucumber-jakarta-cdi/README.md

@@ -95,7 +95,7 @@ or Apache OpenWebBeans.
 
 ## Usage
 
-For each scenario a new CDI container is started. If not present in the
+For each scenario, a new CDI container is started. If not present in the
 container, step definitions are added as unmanaged beans and dependencies are
 injected.
 

cucumber-java/README.md

@@ -1,7 +1,7 @@
 Cucumber Java
 =============
 
-Provides annotation based step definitions. To use, add the `cucumber-java` dependency to your pom.xml:
+Provides annotation-based step definitions. To use, add the `cucumber-java` dependency to your pom.xml:
 
 ```xml
 <dependencies>
@@ -18,7 +18,7 @@ Provides annotation based step definitions. To use, add the `cucumber-java` depe
 
 ## Step Definitions
 
-Declare a step definition by annotating a method. It is possible use the same
+Declare a step definition by annotating a method. It is possible to use the same
 method for multiple steps by repeating the annotation. For localized annotations
 import the annotations from `io.cucumber.java.<ISO2 Language Code>.*`
 
@@ -95,8 +95,8 @@ public class StepDefinitions {
 ```
 
 Note: In addition to collections of `String` collections of `Integer`, `Float`, `BigInteger` and `BigDecimal`, `Byte`, `Short`, `Long`
-and `Double` are also supported. Numbers are parsed using the language of the feature file. To use custom types you can use the
-annotations discussed in "Data Table Type" further down this page.
+and `Double` are also supported. Numbers are parsed using the language of the feature file. To use custom types, you can use the
+annotations discussed in the [Data Table Type](#data-table-type) section below.
 
 ### Doc strings
 
@@ -131,7 +131,7 @@ order can be provided by using the `order` property in the annotation.
 
 `BeforeAll` and `AfterAll` hooks are executed before all scenarios are executed and
 after all scenarios have been executed. A hook is declared by annotating a method.
-This methods must be static and do not take any arguments.
+These methods must be static and do not take any arguments.
 
 ```java
 package io.cucumber.example;
@@ -157,14 +157,14 @@ Notes:
 
  1. When used in combination with Junit 5, Maven Surefire, and/or Failsafe use 
     version `3.0.0-M5` or later.
- 2. When used in combination with Junit 5 and IntelliJ IDEA failures in before
+ 2. When used in combination with Junit 5 and IntelliJ IDEA, failures in before
     all and after all hooks do not fail a test run.
 
 ### Before / After
 
 `Before` and `After` hooks are executed before and after each scenario is executed.
 A hook is declared by annotating a method. This method may take an argument of
-`io.cucumber.java.Scenario`. A tag-expression can be used to execute a hook
+`io.cucumber.java.Scenario`. A [tag-expression](https://github.com/cucumber/tag-expressions) can be used to execute a hook
 conditionally.
 
 ```java
@@ -191,8 +191,8 @@ public class StepDefinitions {
 
 `BeforeStep` and `AfterStep` hooks are executed before and after each step is
 executed. A hook is declared by annotating a method. This method may take an
-argument of `io.cucumber.java.Scenario`. A tag-expression can be used to execute
-a hook  conditionally.
+argument of `io.cucumber.java.Scenario`. A [tag-expression](https://github.com/cucumber/tag-expressions) can be used to execute
+a hook conditionally.
 
 ```java
 package io.cucumber.example;
@@ -216,8 +216,8 @@ public class StepDefinitions {
 
 ## Transformers 
 
-Cucumber expression parameters, data tables and docs strings can be transformed
-into arbitrary java objects.
+Cucumber expression parameters, data tables, and doc strings can be transformed
+into arbitrary Java objects.
 
 ### Parameter Type
 
@@ -288,13 +288,13 @@ public class StepDefinitions {
 ```
 
 Data table types can be declared by annotating a method with `@DataTableType`. 
-Depending on the parameter type this will be either a: 
+Depending on the parameter type, this will be one of the following: 
  * `String` -> `io.cucumber.datatable.TableCellTranformer`
  * `Map<String,String>` -> `io.cucumber.datatable.TableEntryTransformer`
  * `List<String` -> `io.cucumber.datatable.TableRowTranformer`
  * `DataTable` -> `io.cucumber.datatable.TableTransformer`
 
-For a full list of transformations that can be achieved with data table types
+For a full list of transformations that can be achieved with data table types, 
 see [cucumber/datatable](https://github.com/cucumber/cucumber/tree/master/datatable)
 
 ### Default Transformers
@@ -334,7 +334,7 @@ public class DataTableStepDefinitions {
 Data tables in Gherkin cannot represent null or an empty string unambiguously. Cucumber will interpret empty cells as
 `null`.
 
-The empty string can be represented using a replacement. For example `[empty]`.
+The empty string can be represented using a replacement, for example `[blank]`.
 The replacement can be configured by setting the `replaceWithEmptyString`
 property of `DataTableType`, `DefaultDataTableCellTransformer` and 
 `DefaultDataTableEntryTransformer`. By default, no replacement is configured. 
@@ -399,7 +399,7 @@ public class DataTableStepDefinitions {
         return cell;
     }
 
-    @Given("A blank value")
+    @Given("a blank value")
     public void given_a_blank_value(Map<String, String> map){
         // map contains { "key":"a", "value": ""}
     }
@@ -437,14 +437,14 @@ public class DataTableStepDefinitions {
     public User convert(Map<String, String> entry){
       return new User(
          entry.get("firstname"),
-         entry.get("lastname")
+         entry.get("lastname"),
          entry.get("nationality")
       );
     }
 
     @Given("the user is")
     public void the_user_is(@Transpose User user){
-      // user  = [User(firstname="Roberto", lastname="Lo Giacco", nationality="Italian")
+      // user = [User(firstname="Roberto", lastname="Lo Giacco", nationality="Italian")
     }
 }
 ```