JERSEY-2591: Documentation of a package scan inheritance

Change-Id: I62e5dffae423bb0c1b3734d07b27657d6ef5ffb3

Author: Petr Bouda

core-server/src/main/java/org/glassfish/jersey/server/ResourceConfig.java

@@ -51,6 +51,7 @@
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
+import javax.ws.rs.Path;
 import javax.ws.rs.RuntimeType;
 import javax.ws.rs.core.Application;
 import javax.ws.rs.core.Configurable;
@@ -646,6 +647,9 @@ public final ResourceConfig setClassLoader(final ClassLoader classLoader) {
     /**
      * Adds array of package names which will be used to scan for components.
      * <p/>
+     * Package scanning ignores inheritance and therefore {@link Path} annotation
+     * on parent classes and interfaces will be ignored.
+     * <p/>
      * Packages will be scanned recursively, including all nested packages.
      *
      * @param packages array of package names.
@@ -658,7 +662,10 @@ public final ResourceConfig packages(final String... packages) {
 
     /**
      * Adds array of package names which will be used to scan for components.
-     *
+     * <p/>
+     * Package scanning ignores an inheritance and therefore {@link Path} annotation
+     * on parent classes and interfaces will be ignored.
+     * <p/>
      * @param recursive defines whether any nested packages in the collection of specified
      *                  package names should be recursively scanned (value of {@code true})
      *                  as part of the package scanning or not (value of {@code false}).

docs/src/main/docbook/deployment.xml

@@ -101,7 +101,13 @@
             <literal>getClasses</literal>. For example, the following application class that extends from
             &lit.jersey.server.ResourceConfig; scans during deployment for JAX-RS components in packages
             <literal>org.foo.rest</literal> and <literal>org.bar.rest</literal>:
-
+            <note>
+                <para>
+                    <emphasis>Package scanning</emphasis> ignores an inheritance and therefore &lit.jaxrs.Path; annotation
+                    on parent classes and interfaces will be ignored. These classes won't be registered as the JAX-RS component
+                    classes.
+                </para>
+            </note>
             <example>
                 <title>Reusing Jersey implementation in your custom application model</title>
                 <programlisting language="java" linenumbering="numbered">public class MyApplication extends ResourceConfig {