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

Signed-off-by: A.Arnold <[email protected]>

Author: anarnold97

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

@@ -352,13 +352,16 @@ when:
 
 ===== `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 +374,90 @@ 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]
+====
+When matching against packages, as in the previous example, the asterisk must not be after a 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
+----
+
+// Module included in the following assemblies:
+//
+// * docs/rules-development-guide/master.adoc
+
+:_mod-docs-content-type: REFERENCE
+[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 template 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:
+
+[source,yaml]
+----
+- ruleID: lang-ref-004
+   customVariables:
+   - pattern: '([A-z]+)\.get\(\)' # <1>
+      name: VariableName # <2>
+    message: "Found generic call - {{ VariableName }}" # <3>
+  when:
+      java.referenced:
+          location: METHOD_CALL
+          pattern: com.example.apps.GenericClass.get
+----
+<1> `pattern`: A regular expression pattern that is matched on the source code line when a match is found.
+<2> `name`: The name of the variable that can be used in templates.
+<3> `message`: A template for a message using a custom variable.
 
 ===== `go` provider