<commit_before>== Understanding The Found Differences

=== Identifying Problematic Element

When Revapi reports the found API problems it needs to pinpoint the element it is "talking about".
Therefore it assigns a one-line representation to each API element to identify it. It tries to follow the conventions of
Java syntax but needs to go beyond it to express additional information.

First, let's go through some simple examples.

  class com.example.MyClass

This somewhat obviously refers to a class called `MyClass` in the `com.example` package.

  class com.example.MyGenericClass<T extends java.lang.Number>

This again refers to the class but you can see that Revapi also includes the type parameters in the class name. Note
that the bounds of the type parameters are specified using fully qualified class names.

  interface com.example.MyInterface

Here we see that different kinds of classes are distinguished. Revapi uses `@interface` for annotation types, `enum` for
enumerations, `interface` for interfaces and `class` for ordinary classes.

  missing-class com.example.Whoops

What's this? Here, Revapi tries to convey that the class in question wasn't found anywhere on the classpath.

  method java.lang.String com.example.MyClass::myMethod(int, long)

If you are familiar with the method reference syntax in Java 8, you may guess that the above refers to a method called
`myMethod` declared in the `com.example.MyClass` class that returns a `java.lang.String` and accepts an `int` as its
first argument and a `long` as its second argument. As with classes, the type mentioned in the method identifier may
include the type parameters. The method identifier also includes the `throws` declaration if present on the method.

  parameter java.lang.String com.example.MyClass::myMethod(int, ===long===)

If Revapi needs to "talk" about a single parameter of a method, it encloses the parameter in `===`. The above therefore
identifies the second parameter of the method `myMethod`.

  field com.example.MyClass.myField

Quite intuitively, the above identifies the field called `myField` in the class `com.example.MyClass`.

  method void com.example.MySuperClass::superMethod() @ com.example.MyClass

This is again a little bit cryptic. The above identifies the method `superMethod` declared in `com.example.MySuperClass`
as seen in `com.example.MyClass`. In another words, Revapi distinguishes between a declared method and inherited method.
This is because a public method in a private class can be made "accessible" in the API if the private class is inherited
by some public class in the API.

Types::
```
class the.fully.qualified.class.name.including.Any<Type extends Params>
```
where `class` can be `class`, `interface`, `enum` or `@interface` depending on the kind of class in question, or in case
the type is missing in the API:
```
missing-class fully.qualified.class.name.including.Any<Type extends Params>
```

Methods::
Declared method:
```
method ReturnType fully.qualified.class.name.of.the.declaring.class::methodName(All, The, Params) throws Any, Exceptions
```
Inherited method:
```
method ReturnType fully.qualified.class.name.of.the.declaring.class::methodName(All, The, Params) throws Any, Exceptions @ the.class.that.inherits.the.Method
```
Revapi distinguishes between declared and inherited methods because a public method in a private class can be made
"accessible" in the API if the private class is inherited by some public class in the API.

Method Parameters::
This is where the syntax differs most from java. The `===` highlight the parameter
in question among the others. Note also that the parameter names are not available because more often than not they're
not available in the bytecode.

Parameter on a declared method:
```
parameter ReturnType class.name.of.declaring.class::methodName(===ParameterType===, Other, Params)
```
Parameter on an inherited method:
```
parameter ReturnType class.name.of.declaring.class::methodName(===ParameterType===, Other, Params) @ class.name.of.inheriting.class
```
Because method parameter is tied to the method, the distinction between a declared and inherited method is exhibited
in the identifier of the method parameter, too.

Fields::
Declared field:
```
field fully.qualified.class.name.of.declaring.class.fieldName
```
Inherited field:
```
field fully.qualified.class.name.of.declaring.class.fieldName @ class.that.inherits.the.Field
```
As with methods, the distinction between a declared and inherited field is quite important.

==== Match Parameters
In addition to a human-readable representation of the element outlined above, the differences can also be matched by
their additional parameters. Each of the below differences lists the parameters that can be matched against.

For example the `java.class.noLongerImplementsInterface` difference defines the match parameter `interface`. This can
be used when matching the difference for example in the `revapi.ignore` extension:
```javascript
{
  "regex": true,
  "code": "java.class.noLongerImplementsInterface",
  "old": {
    "element": "class my\\..*",
    "interface": "my\\.Interface"
  }
}
```

The above will instruct Revapi to not report the removal of `my.Interface` from the list of implemented interfaces on
any class in the `my` package (or any other subpackage).

All types of differences report the `elementKind` parameter that can have 1 of the following values:
[cols="35s,<65d"]
|=============
|`class` | The element is an ordinary class
|`interface` | The element is an interface
|`enum` | The element is an enum class
|`@interface` | The element is an annotation class
|`constructor` | The element is a constructor
|`enumConstant` | The element is an enum constant
|`field` | The element is a field<commit_msg>[#66] Fix the docs about match parameters.<commit_after>== Understanding The Found Differences

=== Identifying Problematic Element

When Revapi reports the found API problems it needs to pinpoint the element it is "talking about".
Therefore it assigns a one-line representation to each API element to identify it. It tries to follow the conventions of
Java syntax but needs to go beyond it to express additional information.

First, let's go through some simple examples.

  class com.example.MyClass

This somewhat obviously refers to a class called `MyClass` in the `com.example` package.

  class com.example.MyGenericClass<T extends java.lang.Number>

This again refers to the class but you can see that Revapi also includes the type parameters in the class name. Note
that the bounds of the type parameters are specified using fully qualified class names.

  interface com.example.MyInterface

Here we see that different kinds of classes are distinguished. Revapi uses `@interface` for annotation types, `enum` for
enumerations, `interface` for interfaces and `class` for ordinary classes.

  missing-class com.example.Whoops

What's this? Here, Revapi tries to convey that the class in question wasn't found anywhere on the classpath.

  method java.lang.String com.example.MyClass::myMethod(int, long)

If you are familiar with the method reference syntax in Java 8, you may guess that the above refers to a method called
`myMethod` declared in the `com.example.MyClass` class that returns a `java.lang.String` and accepts an `int` as its
first argument and a `long` as its second argument. As with classes, the type mentioned in the method identifier may
include the type parameters. The method identifier also includes the `throws` declaration if present on the method.

  parameter java.lang.String com.example.MyClass::myMethod(int, ===long===)

If Revapi needs to "talk" about a single parameter of a method, it encloses the parameter in `===`. The above therefore
identifies the second parameter of the method `myMethod`.

  field com.example.MyClass.myField

Quite intuitively, the above identifies the field called `myField` in the class `com.example.MyClass`.

  method void com.example.MySuperClass::superMethod() @ com.example.MyClass

This is again a little bit cryptic. The above identifies the method `superMethod` declared in `com.example.MySuperClass`
as seen in `com.example.MyClass`. In another words, Revapi distinguishes between a declared method and inherited method.
This is because a public method in a private class can be made "accessible" in the API if the private class is inherited
by some public class in the API.

Types::
```
class the.fully.qualified.class.name.including.Any<Type extends Params>
```
where `class` can be `class`, `interface`, `enum` or `@interface` depending on the kind of class in question, or in case
the type is missing in the API:
```
missing-class fully.qualified.class.name.including.Any<Type extends Params>
```

Methods::
Declared method:
```
method ReturnType fully.qualified.class.name.of.the.declaring.class::methodName(All, The, Params) throws Any, Exceptions
```
Inherited method:
```
method ReturnType fully.qualified.class.name.of.the.declaring.class::methodName(All, The, Params) throws Any, Exceptions @ the.class.that.inherits.the.Method
```
Revapi distinguishes between declared and inherited methods because a public method in a private class can be made
"accessible" in the API if the private class is inherited by some public class in the API.

Method Parameters::
This is where the syntax differs most from java. The `===` highlight the parameter
in question among the others. Note also that the parameter names are not available because more often than not they're
not available in the bytecode.

Parameter on a declared method:
```
parameter ReturnType class.name.of.declaring.class::methodName(===ParameterType===, Other, Params)
```
Parameter on an inherited method:
```
parameter ReturnType class.name.of.declaring.class::methodName(===ParameterType===, Other, Params) @ class.name.of.inheriting.class
```
Because method parameter is tied to the method, the distinction between a declared and inherited method is exhibited
in the identifier of the method parameter, too.

Fields::
Declared field:
```
field fully.qualified.class.name.of.declaring.class.fieldName
```
Inherited field:
```
field fully.qualified.class.name.of.declaring.class.fieldName @ class.that.inherits.the.Field
```
As with methods, the distinction between a declared and inherited field is quite important.

==== Match Parameters
In addition to a human-readable representation of the element outlined above, the differences can also be matched by
their additional parameters. Each of the below differences lists the parameters that can be matched against.

For example the `java.class.noLongerImplementsInterface` difference defines the match parameter `interface`. This can
be used when matching the difference for example in the `revapi.ignore` extension:
```javascript
{
  "regex": true,
  "code": "java\\.class\\.noLongerImplementsInterface",
  "old": "class my\\..*",
  "interface": "my\\.Interface"
}
```

The above will instruct Revapi to not report the removal of `my.Interface` from the list of implemented interfaces on
any class in the `my` package (or any other subpackage).

All types of differences report the `elementKind` parameter that can have 1 of the following values:
[cols="35s,<65d"]
|=============
|`class` | The element is an ordinary class
|`interface` | The element is an interface
|`enum` | The element is an enum class
|`@interface` | The element is an annotation class
|`constructor` | The element is a constructor
|`enumConstant` | The element is an enum constant
|`field` | The element is a field
{'fraction_non_alphanumeric': 0.08226643598615917, 'fraction_numerical': 0.0012110726643598615, 'mean_word_length': 4.974677002583979, 'pattern_counts': {'":': 9, '<': 11, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3946207', 'n_tokens_mistral': 3051, 'n_tokens_neox': 2917, 'n_words': 1460}