Fix #282 Better document include* and exclude* parameters in AbstractAddThirdPartyMojo

src/main/java/org/codehaus/mojo/license/AbstractAddThirdPartyMojo.java

@@ -113,90 +113,147 @@ public abstract class AbstractAddThirdPartyMojo
     protected boolean acceptPomPackaging;
 
     /**
-     * A filter to exclude some scopes.
-     * <p>
-     * Multiple scopes can be delimited by comma, eg. {@code <excludedScopes>test,provided</excludedScopes>}
+     * A comma separated list of scopes to exclude: e.g. {@code <excludedScopes>test,provided</excludedScopes>}
      * or {@code -Dlicense.excludedScopes=test,provided}.
+     * <p>
+     * This filter is applied on the list of direct dependencies (and
+     * their transitive dependencies) of the projects in the reactor.
+     * <p>
+     * By default if an artifact is excluded its transitive dependencies
+     * are not automatically excluded. To enforce this behavior refer to
+     * {@link #excludeTransitiveDependencies}.
      *
      * @since 1.1
      */
     @Parameter( property = "license.excludedScopes", defaultValue = "system" )
     protected String excludedScopes;
 
     /**
-     * A filter to include only some scopes, if let empty then all scopes will be used (no filter).
-     * <p>
-     * Multiple scopes can be delimited by comma, eg. {@code <includedScopes>test,provided</includedScopes>}
+     * A comma separated list of scopes to include: e.g. {@code <includedScopes>test,provided</includedScopes>}
      * or {@code -Dlicense.includedScopes=test,provided}.
+     * <p>
+     * This filter is applied on the list of direct dependencies (and
+     * their transitive dependencies) of the projects in the reactor.
+     * <p>
+     * By default if an artifact is included also its transitive
+     * dependencies are included. To suppress this behavior refer to
+     * {@link #includeTransitiveDependencies}.
      *
      * @since 1.1
      */
     @Parameter( property = "license.includedScopes" )
     protected String includedScopes;
 
     /**
-     * A filter to exclude some types.
+     * A comma separated list of types to exclude: e.g. {@code <excludedTypes>war,pom</excludedTypes>}
+     * or {@code -Dlicense.excludedTypes=was,pom}.
+     * <p>
+     * This filter is applied on the list of direct dependencies (and
+     * their transitive dependencies) of the projects in the reactor.
+     * <p>
+     * By default if an artifact is excluded its transitive dependencies
+     * are not automatically excluded. To enforce this behavior refer to
+     * {@link #excludeTransitiveDependencies}.
      *
      * @since 1.15
      */
     @Parameter( property = "license.excludedTypes" )
     protected String excludedTypes;
 
     /**
-     * A filter to include only some types, if let empty then all types will be used (no filter).
+     * A comma separated list of types to include.
+     * <p>
+     * This filter is applied on the list of direct dependencies (and
+     * their transitive dependencies) of the projects in the reactor.
+     * <p>
+     * By default if an artifact is included also its transitive
+     * dependencies are included. To suppress this behavior refer to
+     * {@link #includeTransitiveDependencies}.
      *
      * @since 1.15
      */
     @Parameter( property = "license.includedTypes" )
     protected String includedTypes;
 
     /**
-     * A filter to exclude some GroupIds
-     * This is a regular expression that is applied to groupIds (not an ant pattern).
+     * A regular expression (not glob pattern) used as filter to exclude
+     * artifacts that have matching groupId. Match could be also partial for
+     * example {@code ^org\.}
+     * <p>
+     * This filter is applied on the list of direct dependencies (and
+     * their transitive dependencies) of the projects in the reactor.
+     * <p>
+     * By default if an artifact is excluded its transitive dependencies
+     * are not automatically excluded. To enforce this behavior refer to
+     * {@link #excludeTransitiveDependencies}.
      *
      * @since 1.1
      */
     @Parameter( property = "license.excludedGroups" )
     protected String excludedGroups;
 
     /**
-     * A filter to include only some GroupIds
-     * This is a regular expression applied to artifactIds.
+     * A regular expression (not glob pattern) used as filter to include
+     * only artifacts that have matching groupId.
+     * <p>
+     * This filter is applied on the list of direct dependencies (and
+     * their transitive dependencies) of the projects in the reactor.
+     * <p>
+     * By default if an artifact is included also its transitive
+     * dependencies are included. To suppress this behavior refer to
+     * {@link #includeTransitiveDependencies}.
      *
      * @since 1.1
-     */
-    @Parameter( property = "license.includedGroups" )
+     */    @Parameter( property = "license.includedGroups" )
     protected String includedGroups;
 
     /**
-     * A filter to exclude some ArtifactsIds
-     * This is a regular expression applied to artifactIds.
+     * A regular expression (not glob pattern) used as filter to exclude
+     * artifacts that have matching artifactId. Match could be also partial for
+     * example {@code ^org\.}
+     * <p>
+     * This filter is applied on the list of direct dependencies (and
+     * their transitive dependencies) of the projects in the reactor.
+     * <p>
+     * By default if an artifact is excluded its transitive dependencies
+     * are not automatically excluded. To enforce this behavior refer to
+     * {@link #excludeTransitiveDependencies}.
      *
      * @since 1.1
      */
     @Parameter( property = "license.excludedArtifacts" )
     protected String excludedArtifacts;
 
     /**
-     * A filter to include only some ArtifactsIds
-     * This is a regular expression applied to artifactIds.
+     * A regular expression (not glob pattern) used as filter to include
+     * only artifacts that have matching artifactId.
+     * <p>
+     * This filter is applied on the list of direct dependencies (and
+     * their transitive dependencies) of the projects in the reactor.
+     * <p>
+     * By default if an artifact is included also its transitive
+     * dependencies are included. To suppress this behavior refer to
+     * {@link #includeTransitiveDependencies}.
      *
      * @since 1.1
      */
     @Parameter( property = "license.includedArtifacts" )
     protected String includedArtifacts;
 
     /**
-     * Include transitive dependencies when checking for missing licenses and downloading license files.
-     * If this is <tt>false</tt>, then only direct dependencies are examined.
+     * If {@code true} enforces including transitive dependencies of the
+     * projects in the reactor; otherwise only direct dependencies of the
+     * reactor projects are considered.
      *
      * @since 1.1
      */
     @Parameter( property = "license.includeTransitiveDependencies", defaultValue = "true" )
     boolean includeTransitiveDependencies;
 
     /**
-     * Exclude transitive dependencies from excluded Artifacts
+     * If {@code true} enforces excluding transitive dependencies of the
+     * excluded artifacts in the reactor; otherwise only artifacts that match
+     * exclude filters are excluded.
      *
      * @since 1.13
      */