Rename Type#getName() to getId() and improve javadoc (#1198)

api/maven-api-core/src/main/java/org/apache/maven/api/Dependency.java

@@ -23,9 +23,9 @@
 public interface Dependency extends Artifact {
 
     /**
-     * The artifact type.
+     * The dependency type.
      *
-     * @return the artifact type, never {@code null}
+     * @return the dependency type, never {@code null}
      */
     @Nonnull
     Type getType();

api/maven-api-core/src/main/java/org/apache/maven/api/Type.java

@@ -20,14 +20,19 @@
 
 import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Immutable;
+import org.apache.maven.api.model.Dependency;
 
 /**
- * An artifact's{@code Type} represents a known kind of artifacts.
- * Such types are often associated to an extension and possibly
- * a classifier, for example {@code java-source} has a {@code jar}
- * extension and a {@code sources} classifier.
- * It is also used to determine if a given dependency should be
- * included in the classpath or if its transitive dependencies should.
+ * A dependency's {@code Type} is uniquely identified by a {@code String},
+ * and semantically represents a known <i>kind</i> of dependency.
+ * <p>
+ * It provides information about the file type (or extension) of the associated artifact,
+ * its default classifier, and how the artifact will be used in the build when creating
+ * classpaths.
+ * <p>
+ * For example, the type {@code java-source} has a {@code jar} extension and a
+ * {@code sources} classifier. The artifact and its dependencies should be added
+ * to the classpath.
  *
  * @since 4.0.0
  */
@@ -43,27 +48,43 @@ public interface Type {
     String TEST_JAR = "test-jar";
 
     /**
-     * Returns the dependency type name.
+     * Returns the dependency type id.
+     * The id uniquely identifies this <i>dependency type</i>.
      *
-     * @return the type name
+     * @return the id of this type
      */
-    String getName();
+    String getId();
 
     /**
-     * Get the file extension associated to the file represented by the dependency type.
+     * Get the file extension of artifacts of this type.
      *
      * @return the file extension
      */
     String getExtension();
 
     /**
-     * Get the classifier associated to the dependency type.
+     * Get the default classifier associated to the dependency type.
+     * The default classifier can be overridden when specifying
+     * the {@link Dependency#getClassifier()}.
      *
-     * @return the classifier
+     * @return the default classifier
      */
     String getClassifier();
 
-    boolean isIncludesDependencies();
-
+    /**
+     * Specifies if the artifact contains java classes and should be
+     * added to the classpath.
+     *
+     * @return if the artifact should be added to the classpath
+     */
     boolean isAddedToClasspath();
+
+    /**
+     * Specifies if the artifact already embeds its own dependencies.
+     * This is the case for JEE packages or similar artifacts such as
+     * WARs, EARs, etc.
+     *
+     * @return if the artifact's dependencies are included in the artifact
+     */
+    boolean isIncludesDependencies();
 }

api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinateFactoryRequest.java

@@ -89,7 +89,7 @@ static DependencyCoordinateFactoryRequest build(@Nonnull Session session, @Nonnu
                 .version(dependency.getVersion().asString())
                 .classifier(dependency.getClassifier())
                 .extension(dependency.getExtension())
-                .type(dependency.getType().getName())
+                .type(dependency.getType().getId())
                 .scope(dependency.getScope().id())
                 .optional(dependency.isOptional())
                 .build();

maven-core/src/main/java/org/apache/maven/internal/impl/DefaultTypeRegistry.java

@@ -52,7 +52,7 @@ public Type getType(String id) {
         boolean addedToClasspath = handler.isAddedToClasspath();
         return new Type() {
             @Override
-            public String getName() {
+            public String getId() {
                 return id;
             }
 

maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java

@@ -356,10 +356,10 @@ void initialize(CliRequest cliRequest) throws ExitException {
         }
         topDirectory = getCanonicalPath(topDirectory);
         cliRequest.topDirectory = topDirectory;
-        // We're very early in the process and we don't have the container set up yet,
-        // so we rely on the JDK services to eventually lookup a custom RootLocator.
+        // We're very early in the process, and we don't have the container set up yet,
+        // so we rely on the JDK services to eventually look up a custom RootLocator.
         // This is used to compute {@code session.rootDirectory} but all {@code project.rootDirectory}
-        // properties will be compute through the RootLocator found in the container.
+        // properties will be computed through the RootLocator found in the container.
         RootLocator rootLocator =
                 ServiceLoader.load(RootLocator.class).iterator().next();
         Path rootDirectory = rootLocator.findRoot(topDirectory);