add

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

Author: anarnold97

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

@@ -392,7 +392,7 @@ java.referenced:
 +
 [WARNING]
 ====
-When matching against packages, as in the previous example, the asterisk must not be after a dot.
+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:
 
 For example:
 
@@ -431,6 +431,95 @@ java.referenced:
   pattern: java.util.List
 ----
 
+====== `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.
+
+
+
 // Module included in the following assemblies:
 //
 // * docs/rules-development-guide/master.adoc