MTA-4637: Pattern matching docs need urgent improvements (quick fix)

docs/topics/create-yaml-rule.adoc

@@ -173,7 +173,7 @@ _Example_
 when:
   java.referenced:
     location: PACKAGE
-    pattern: org.jboss.*
+    pattern: org.jboss*
 ----
 
 . Create an `AND` or `OR` condition

docs/topics/yaml-rule-structure-syntax.adoc

@@ -228,7 +228,8 @@ when:
 
 {ProductShortName} supports three types of conditions: `provider`, `and`, and `or`.
 
-==== Provider conditions
+[id="yaml-provider-conditions_{context}"]
+== Provider conditions
 
 The Application Analyzer detects the programming languages, frameworks, and tools used to build an application, and it generates default rulesets for each supported provider using the Language Server Protocol (LSP) accordingly.
 Each supported provider has a ruleset defined by default and is run independently in a separate container.
@@ -273,7 +274,8 @@ a|
 * Node.js
 |===
 
-===== `builtin` provider
+[id="yaml-builtin-provider_{context}"]
+=== `builtin` provider
 
 `builtin` is an internal provider that can analyze various files and internal metadata generated by the engine.
 
@@ -350,15 +352,19 @@ when:
 ----
 <1> When more than one tag is given, a logical AND is implied.
 
-===== `java` provider
+[id="yaml-java-provider_{context}"]
+=== `java` provider
 
-The `java` provider analyzes Java source code.
+The Language Server used by the Java provider is Eclipse’s JDT Language Server (JDTLS). Internally, the JDTLS uses the Eclipse Java Development Toolkit, which includes utilities for searching code in projects.
 
 This provider has the following capabilities:
 
 * `referenced`
 * `dependency`
 
+In the `pattern` element of a `java.referenced` condition, you can search through application code by using these utilities. For more details, see link:https://help.eclipse.org/latest/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fjdt%2Fcore%2Fsearch%2FSearchPattern.html&anchor=createPattern[Class SearchPattern], which  contains all the information for building these patterns for `createPattern(String, int, int, int)`.
+
+
 .`referenced`
 
 The `referenced` capability enables the provider to find references in the source code. This capability takes three input parameters: `pattern`, `location`, and `annotated`.
@@ -371,49 +377,151 @@ when:
     location: "<location>" <2>
     annotated: "<annotated>" <3>
 ----
-<1> A regular expression pattern to match, for example, `org.kubernetes.*`.
+<1> A regular expression pattern to match, for example, `org.kubernetes*`.
 <2> Specifies the exact location where the pattern needs to be matched, for example, `IMPORT`.
 <3> Checks for specific annotations and their elements, such as name and value in the Java code using a query. For example, the following query matches the Bean(url = “http://www.example.com”) annotation in the method.
+
+
+.Examples
+
+* Search for any class under the `javax.xml` package, occurring in any
+location:
 +
-[source,terminal]
+[source,yaml]
 ----
- annotated:
-      pattern: org.framework.Bean
-      elements:
-      - name: url
-        value: "http://www.example.com"
+java.referenced:
+  pattern: javax.xml*
 ----
++
+[WARNING]
+====
+If you want to match using an asterisk `*` wildcard for a wider range of results, it is recommended to place it directly after the package, not after the dot:
 
-The supported locations are the following:
+For example:
 
-* `CONSTRUCTOR_CALL`
-* `TYPE`
-* `INHERITANCE`
-* `METHOD_CALL`
-* `ANNOTATION`
-* `IMPLEMENTS_TYPE`
-* `ENUM_CONSTANT`
-* `RETURN_TYPE`
-* `IMPORT`
-* `VARIABLE_DECLARATION`
-* `FIELD`
-* `METHOD`
+* `pattern: javax.xml*`
++
+and not:
 
-.`dependency`
+* `pattern: javax.xml.*`
+====
 
-The `dependency` capability  enables the provider to find dependencies for a given application. {ProductShortName} generates a list of the application's dependencies, and you can use this capability to query the list and check whether a certain dependency exists for the application within a given range of the dependency's versions.
+* Search for method declarations that return `java.lang.String`:
++
+[source,yaml]
+----
+java.referenced:
+  location: METHOD
+  pattern: '* java.lang.String'
+----
 
-[source,terminal]
+* Search for a method named "`method`" declared on `org.konveyor.MyClass`
+that returns a `List` of a type that extends `java.lang.String`:
++
+[source,yaml]
 ----
-when:
-  java.dependency:
-    name: "<dependency_name>" <1>
-    upperbound: "<version_string>" <2>
-    lowerbound: "<version_string>" <3>
+java.referenced:
+  location: METHOD
+  pattern: 'org.konveyor.Myclass.method(*) java.util.List<? extends java.lang.String>'
 ----
-<1> Name of the dependency to search for.
-<2> Upper bound on the version of the dependency.
-<3> Lower bound on the version of the dependency.
+
+* Search for a class that implements `java.util.List`:
++
+[source,yaml]
+----
+java.referenced:
+  location: IMPLEMENTS_TYPE
+  pattern: java.util.List
+----
+
+[id="yaml-java-locations_{context}"]
+==== `java` locations
+
+The Java provider allows scoping down the search to certain source code locations. You can scope down Java searches from any one of the following search locations:
+
+* *IMPORT*: IMPORT allows for searches on class imports. It can either be used with a fully qualified domain name (FQDN) or an asterisk as a wildcard to allow for wider matches:
++
+For example:
++
+[source,yaml]
+----
+java.referenced:
+  pattern: org.apache.lucene.search*
+  location: IMPORT
+----
+
++
+This scope would match on each of these imports:
++
+[source,java]
+----
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.Sort;
+import org.apache.lucene.search.SortField;
+----
++
+If you want to match using an asterisk `*` wildcard for a wider range of results, it is recommended to place it directly after the package, not after the dot:
+
+** Use: `org.apache.lucene.search*`
+
+** Do not use: `org.apache.lucene.search.*`
+
+
+* *PACKAGE*: PACKAGE allows for searches on any usage of a package, be it in an import or used as part of a FQDN in the code:
++
+[source,yaml]
+----
+java.referenced:
+  pattern: org.apache.lucene.search*
+  location: PACKAGE
+----
++
+This scope would match on both the import and the fully qualified usage:
++
+[source,java]
+----
+import org.apache.lucene.search.*;
+----
++
+[source,java]
+----
+public class Test {
+  private org.apache.lucene.search.Query query;
+}
+----
++
+If you want to match using an asterisk `*` wildcard for a wider range of results, it is recommended to place it directly after the package, not after the dot.
+
+
+* *CONSTRUCTOR_CALL* and *METHOD_CALL*: for matching constructors and methods, respectively. The pattern possibilities are varied, and it is possible to match against specific return types, arguments, and so on.
++
+For instance, looking for a method named `method` declared in the `org.konveyor.MyClass` that returns a `List` of a type that extends `java.lang.String` and accepts a single parameter:
++
+[source,yaml]
+----
+java.referenced:
+  location: METHOD
+  pattern: 'org.konveyor.Myclass.method(*) java.util.List<? extends java.lang.String>'
+----
+
+More information about the possibilities of these patterns can be found in the link:[Class SearchPattern section] of the Eclipse documentation, which contain all the required information for building these patterns.
+
+[WARNING]
+====
+In the current release of {ProductShortName}, fully qualified static method matching does not function as expected.
+====
+
+* *TYPE*: matches against types in general, appearing anywhere.
+* *INHERITANCE*: matches against a class inheriting from a given type.
+* *ANNOTATION*: matches against annotations.
+* *IMPLEMENTS_TYPE*: matches against any type implementing the given type.
+* *ENUM_CONSTANT*: matches against `enum` constants.
+* *RETURN_TYPE*: matches against a type being returned by a method.
+* *VARIABLE_DECLARATION*: matches against a type being declared as a variable.
+* *FIELD* (declaration): matches against a type appearing in a field declaration. It can be coupled with an annotation match, this being an annotation happening on the field.
+* *METHOD*: matches against a given method declaration. It can be coupled with an annotation match.
+* *CLASS* (declaration): matches against a given method declaration. It can be coupled with an annotation match.
+
 
 ===== `go` provider