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 @@
 
 {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 @@
 * 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,16 +352,20 @@
 ----
 <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`
 
-.`referenced`
+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)`.
+
+[id="yaml-java-referenced_{context}"]
+=== `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,7 +377,7 @@
     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.
 +
@@ -384,22 +390,60 @@
         value: "http://www.example.com"
 ----
 
-The supported locations are the following:
+.Examples
+
+* Search for any class under the `javax.xml` package, occurring in any
+location:
++
+[source,yaml]
+----
+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:
 
-* `CONSTRUCTOR_CALL`
-* `TYPE`
-* `INHERITANCE`
-* `METHOD_CALL`
-* `ANNOTATION`
-* `IMPLEMENTS_TYPE`
-* `ENUM_CONSTANT`
-* `RETURN_TYPE`
-* `IMPORT`
-* `VARIABLE_DECLARATION`
-* `FIELD`
-* `METHOD`
+For example:
 
-.`dependency`
+* `pattern: javax.xml*`
++
+and not:
+
+* `pattern: javax.xml.*`
+====
+
+* Search for method declarations that return `java.lang.String`:
++
+[source,yaml]
+----
+java.referenced:
+  location: METHOD
+  pattern: '* java.lang.String'
+----
+
+* 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]
+----
+java.referenced:
+  location: METHOD
+  pattern: 'org.konveyor.Myclass.method(*) java.util.List<? extends java.lang.String>'
+----
+
+* Search for a class that implements `java.util.List`:
++
+[source,yaml]
+----
+java.referenced:
+  location: IMPLEMENTS_TYPE
+  pattern: java.util.List
+----
+
+[id="yaml-java-dependency_{context}"]
+=== `dependency`
 
 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.
 
@@ -415,7 +459,95 @@
 <2> Upper bound on the version of the dependency.
 <3> Lower bound on the version of the dependency.
 
-===== `go` provider
+[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.
+
+[id="yaml-go-provider_{context}"]
+== `go` provider
 
 The `go` provider analyzes Go source code. This provider's capabilities are `referenced` and `dependency`.
 
@@ -445,7 +577,8 @@
 <2> Upper bound on the version of the dependency.
 <3> Lower bound on the version of the dependency.
 
-===== `dotnet` provider
+[id="yaml-dotnet-provider_{context}"]
+== `dotnet` provider
 
 The `dotnet` is an external provider used to analyze .NET and C# source code. Currently, the provider supports the `referenced` capability.
 
@@ -460,10 +593,11 @@
     pattern: "<pattern>" <1>
     namespace: "<namespace>" <2>
 ----
 <1> `pattern`: A regex pattern to match the desired reference. For example, HttpNotFound.
 <2> `namespace`: Specifies the namespace to search within. For example, System.Web.Mvc.
 
-==== Custom variables
+[id="yaml-custom-variables_{context}"]
+== Custom variables
 
 Provider conditions can have associated custom variables. You can use custom variables to capture relevant information from the matched line in the source code. The values of these variables are interpolated with data matched in the source code. These values can be used to generate detailed templated messages in a rule's action (see xref:yaml-rule-actions_{context}[Message actions]). They can be added to a rule in the `customVariables` field:
 
@@ -484,12 +618,13 @@
 <2> `name`: The name of the variable that can be used in templates.
 <3> `message`: A template for a message using a custom variable.
 
-
-=== Logical conditions
+[id="yaml-logical-conditions_{context}"]
+== Logical conditions
 
 The analyzer provides two basic logical conditions, `and` and `or`, which enable you to aggregate results of other conditions and create more complex queries.
 
-==== `and` condition
+[id="yaml-logical-and_{context}"]
+=== `and` condition
 
 The `and` condition performs a logical AND operation on the results of an array of conditions. An `and` condition matches when _all_ of its child conditions match.
 
@@ -532,7 +667,8 @@
   - go.referenced: "*CustomResourceDefinition*"
 ----
 
-==== `or` condition
+[id="yaml-logical-or_{context}"]
+=== `or` condition
 
 The `or` condition performs a logical OR operation on the results of an array of conditions. An `or` condition matches when _any_ of its child conditions matches.
 
@@ -559,6 +695,7 @@
       pattern: junit.junit
 ----
 
+[id="yaml-rulesets_{context}"]
 == Rulesets
 
 A set of rules forms a ruleset. {ProductShortName} does not require every rule file to belong to a ruleset, but you can use rulesets to group multiple rules that achieve a common goal and to pass the rules to the rules engine.