Fix typos and linguistic errors in documentation (#846)

Signed-off-by: Sebastien Dionne <survivant00@gmail.com>

Author: survivant

CONTRIBUTING.md

@@ -8,5 +8,5 @@
 - File a PR with meaningful title, description and commit messages
 - Make sure the option "Allow edits from maintainers" in the PR is selected so that the maintainers can update your PRs with minor fixes, if needed.
 - Recommended git settings
-   - `git config core.autocrlf input` to tell Git convert CRLF to LF on commit but not the other way around 
+   - `git config core.autocrlf input` to tell Git to convert CRLF to LF on commit but not the other way around 
 - To close an issue (e.g. issue 1542) automatically after a PR is merged, use keywords "fix", "close", "resolve" in the PR description, e.g. `fix #1542`. (Ref: [closing issues using keywords](https://help.github.com/articles/closing-issues-using-keywords/))

README.md

@@ -1,6 +1,6 @@
 # OpenAPI-diff 
 
-Compare two OpenAPI specifications (3.x) and render the difference to HTML plaintext, Markdown files, or JSON files.
+Compare two OpenAPI specifications (3.x) and render the difference to HTML plain text, Markdown files, or JSON files.
 
 [![Build](https://github.com/OpenAPITools/openapi-diff/workflows/Main%20Build/badge.svg)](https://github.com/OpenAPITools/openapi-diff/actions?query=branch%3Amaster+workflow%3A"Main+Build")
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=OpenAPITools_openapi-diff&metric=alert_status)](https://sonarcloud.io/dashboard?id=OpenAPITools_openapi-diff)
@@ -20,7 +20,7 @@ Compare two OpenAPI specifications (3.x) and render the difference to HTML plain
 # Feature
 
 * Supports OpenAPI spec v3.0.
-* Depth comparison of parameters, responses, endpoint, http method (GET,POST,PUT,DELETE...)
+* In-depth comparison of parameters, responses, endpoint, http method (GET,POST,PUT,DELETE...)
 * Supports swagger api Authorization
 * Render difference of property with Expression Language
 * HTML, Markdown, Asciidoc & JSON render
@@ -195,9 +195,9 @@ public class Main {
 
 ### Path Matching while comparing two OpenAPI paths
 
-Path matching controls how paths from the old and new specs are paired during comparison (PathsDiff.java). The default matcher (DefaultPathMatcher) obfuscates path parameter names, meaning `/users/{id}` matches `/users/{userId}`. Default matcher fails on ambiguous signatures if spec contains few paths semantically identical. In case this behaviour is not fitting your use case, you can implement your own matching strategy.
+Path matching controls how paths from the old and new specs are paired during comparison (PathsDiff.java). The default matcher (DefaultPathMatcher) obfuscates path parameter names, meaning `/users/{id}` matches `/users/{userId}`. The default matcher fails on ambiguous signatures if the spec contains a few paths semantically identical. In case this behaviour is not fitting your use case, you can implement your own matching strategy.
 
-You can plug in a custom matcher via `OpenApiDiffOptions` implementing the `PathMatcher` interface.:
+You can plug in a custom matcher via `OpenApiDiffOptions` implementing the `PathMatcher` interface:
 
 ```java
 OpenApiDiffOptions options = OpenApiDiffOptions
@@ -249,7 +249,7 @@ jsonRender.render(diff, outputStreamWriter);
 
 ### Extensions
 
-This project uses Java Service Provider Inteface (SPI) so additional extensions can be added. 
+This project uses Java Service Provider Interface (SPI) so additional extensions can be added. 
 
 To build your own extension, you simply need to create a `src/main/resources/META-INF/services/org.openapitools.openapidiff.core.compare.ExtensionDiff` file with the full classname of your implementation.
 Your class must also implement the `org.openapitools.openapidiff.core.compare.ExtensionDiff` interface.

cli/src/main/java/org/openapitools/openapidiff/cli/Main.java

@@ -90,7 +90,7 @@ public static void main(String... args) {
             .numberOfArgs(2)
             .valueSeparator()
             .argName("property=value")
-            .desc("use given header for authorisation")
+            .desc("use given header for authorization")
             .build());
     options.addOption(
         Option.builder()
@@ -99,7 +99,7 @@ public static void main(String... args) {
             .numberOfArgs(2)
             .valueSeparator()
             .argName("property=value")
-            .desc("use query param for authorisation")
+            .desc("use query param for authorization")
             .build());
     options.addOption(
         Option.builder()
@@ -187,7 +187,7 @@ public static void main(String... args) {
             && !logLevel.equalsIgnoreCase("OFF")) {
           throw new ParseException(
               String.format(
-                  "Invalid log level. Excepted: [TRACE, DEBUG, INFO, WARN, ERROR, OFF]. Given: %s",
+                  "Invalid log level. Expected: [TRACE, DEBUG, INFO, WARN, ERROR, OFF]. Given: %s",
                   logLevel));
         }
       }

core/src/main/java/org/openapitools/openapidiff/core/OpenApiCompare.java

@@ -21,22 +21,22 @@ public class OpenApiCompare {
   private OpenApiCompare() {}
 
   /**
-   * compare two openapi doc
+   * Compare two OpenAPI documents.
    *
-   * @param oldContent old api-doc location:Json or Http
-   * @param newContent new api-doc location:Json or Http
+   * @param oldContent old API document location: JSON or HTTP
+   * @param newContent new API document location: JSON or HTTP
    * @return Comparison result
    */
   public static ChangedOpenApi fromContents(String oldContent, String newContent) {
     return fromContents(oldContent, newContent, null);
   }
 
   /**
-   * compare two openapi doc
+   * Compare two OpenAPI documents.
    *
-   * @param oldContent old api-doc location:Json or Http
-   * @param newContent new api-doc location:Json or Http
-   * @param auths
+   * @param oldContent old API document location: JSON or HTTP
+   * @param newContent new API document location: JSON or HTTP
+   * @param auths authorization values
    * @return Comparison result
    */
   public static ChangedOpenApi fromContents(
@@ -45,12 +45,12 @@ public static ChangedOpenApi fromContents(
   }
 
   /**
-   * compare two openapi doc
+   * Compare two OpenAPI documents.
    *
-   * @param oldContent old api-doc location:Json or Http
-   * @param newContent new api-doc location:Json or Http
-   * @param auths
-   * @param options
+   * @param oldContent old API document location: JSON or HTTP
+   * @param newContent new API document location: JSON or HTTP
+   * @param auths authorization values
+   * @param options comparison options
    * @return Comparison result
    */
   public static ChangedOpenApi fromContents(
@@ -63,22 +63,22 @@ public static ChangedOpenApi fromContents(
   }
 
   /**
-   * compare two openapi doc
+   * Compare two OpenAPI documents.
    *
-   * @param oldFile old api-doc file
-   * @param newFile new api-doc file
+   * @param oldFile old API document file
+   * @param newFile new API document file
    * @return Comparison result
    */
   public static ChangedOpenApi fromFiles(File oldFile, File newFile) {
     return fromFiles(oldFile, newFile, null);
   }
 
   /**
-   * compare two openapi doc
+   * Compare two OpenAPI documents.
    *
-   * @param oldFile old api-doc file
-   * @param newFile new api-doc file
-   * @param auths
+   * @param oldFile old API document file
+   * @param newFile new API document file
+   * @param auths authorization values
    * @return Comparison result
    */
   public static ChangedOpenApi fromFiles(
@@ -87,12 +87,12 @@ public static ChangedOpenApi fromFiles(
   }
 
   /**
-   * compare two openapi doc
+   * Compare two OpenAPI documents.
    *
-   * @param oldFile old api-doc file
-   * @param newFile new api-doc file
-   * @param auths
-   * @param options
+   * @param oldFile old API document file
+   * @param newFile new API document file
+   * @param auths authorization values
+   * @param options comparison options
    * @return Comparison result
    */
   public static ChangedOpenApi fromFiles(
@@ -101,22 +101,22 @@ public static ChangedOpenApi fromFiles(
   }
 
   /**
-   * compare two openapi doc
+   * Compare two OpenAPI documents.
    *
-   * @param oldLocation old api-doc location (local or http)
-   * @param newLocation new api-doc location (local or http)
+   * @param oldLocation old API document location (local or HTTP)
+   * @param newLocation new API document location (local or HTTP)
    * @return Comparison result
    */
   public static ChangedOpenApi fromLocations(String oldLocation, String newLocation) {
     return fromLocations(oldLocation, newLocation, null);
   }
 
   /**
-   * compare two openapi doc
+   * Compare two OpenAPI documents.
    *
-   * @param oldLocation old api-doc location (local or http)
-   * @param newLocation new api-doc location (local or http)
-   * @param auths
+   * @param oldLocation old API document location (local or HTTP)
+   * @param newLocation new API document location (local or HTTP)
+   * @param auths authorization values
    * @return Comparison result
    */
   public static ChangedOpenApi fromLocations(
@@ -125,12 +125,12 @@ public static ChangedOpenApi fromLocations(
   }
 
   /**
-   * compare two openapi doc
+   * Compare two OpenAPI documents.
    *
-   * @param oldLocation old api-doc location (local or http)
-   * @param newLocation new api-doc location (local or http)
-   * @param auths
-   * @param options
+   * @param oldLocation old API document location (local or HTTP)
+   * @param newLocation new API document location (local or HTTP)
+   * @param auths authorization values
+   * @param options comparison options
    * @return Comparison result
    */
   public static ChangedOpenApi fromLocations(
@@ -143,22 +143,22 @@ public static ChangedOpenApi fromLocations(
   }
 
   /**
-   * compare two openapi doc
+   * Compare two OpenAPI documents.
    *
-   * @param oldSpec old api-doc specification
-   * @param newSpec new api-doc specification
+   * @param oldSpec old API document specification
+   * @param newSpec new API document specification
    * @return Comparison result
    */
   public static ChangedOpenApi fromSpecifications(OpenAPI oldSpec, OpenAPI newSpec) {
     return fromSpecifications(oldSpec, newSpec, OpenApiDiffOptions.builder().build());
   }
 
   /**
-   * compare two openapi doc
+   * Compare two OpenAPI documents.
    *
-   * @param oldSpec old api-doc specification
-   * @param newSpec new api-doc specification
-   * @param options
+   * @param oldSpec old API document specification
+   * @param newSpec new API document specification
+   * @param options comparison options
    * @return Comparison result
    */
   public static ChangedOpenApi fromSpecifications(

core/src/main/java/org/openapitools/openapidiff/core/compare/MapKeyDiff.java

@@ -6,7 +6,7 @@
 import java.util.Map;
 import java.util.Map.Entry;
 
-/** compare two Maps by key */
+/** Compare two Maps by key. */
 public class MapKeyDiff<K, V> {
 
   private Map<K, V> increased;

core/src/main/java/org/openapitools/openapidiff/core/compare/ParametersDiff.java

@@ -28,7 +28,7 @@ public ParametersDiffResult(
     this.sameOperationsDiffSchema = sameOperationsDiffSchema;
   }
 }
-/** compare two parameter */
+/** Compare two parameters. */
 public class ParametersDiff {
 
   private static final RefPointer<Parameter> refPointer = new RefPointer<>(RefType.PARAMETERS);
@@ -108,12 +108,12 @@ public boolean pathUnchangedParametersChanged(
               .findFirst();
       if (!newParameter.isPresent()) return false;
 
-      // Check if  the old and new Parameters match . IF so, return TRUE
+      // Check if the old and new Parameters match. IF so, return TRUE
       Parameter newParameterRealized = newParameter.get();
       newParameterRealized.setName(parameter.getName()); // Make names similar
       boolean samePathDifferentParameter = !newParameterRealized.equals(parameter);
       newParameterRealized.setName(
-          newParameterName); // Important:: MUST Reset the name as this is not a copy
+          newParameterName); // Important: MUST Reset the name as this is not a copy
       if (samePathDifferentParameter) {
         return true;
       }