Fix javadoc

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

@@ -65,7 +65,7 @@ public interface Dependency extends Artifact {
     boolean isOptional();
 
     /**
-     * {@return coordinate with the same identifiers as this dependency}.
+     * {@return coordinate with the same identifiers as this dependency}
      */
     @Nonnull
     @Override

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

@@ -23,13 +23,13 @@
 import org.apache.maven.api.annotations.Experimental;
 
 /**
- * An {@link Artifact} that is being produced by a {@link Project}.
+ * An {@link Artifact} that is being produced by a {@link Project} during the build.
  *
- * <p>Produced artifacts includes:<ul>
+ * <p>Produced artifacts includes:</p><ul>
  *     <li>{@linkplain Project#getPomArtifact() the project POM artifact}</li>
  *     <li>{@linkplain Project#getMainArtifact() the main artifact}</li>
  *     <li>{@linkplain org.apache.maven.api.services.ProjectManager#attachArtifact(Session, Project, Path) artifacts to be attached to a project}</li>
- * </ul></p>
+ * </ul>
  *
  * <p>For the main artifact and attached artifacts, the
  * {@link org.apache.maven.api.services.ArtifactManager ArtifactManager} service must be used

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

@@ -29,10 +29,10 @@
 
 /**
  * Interface representing a Maven project which can be created using the
- * {@link org.apache.maven.api.services.ProjectBuilder} service.
+ * {@link org.apache.maven.api.services.ProjectBuilder ProjectBuilder} service.
  * Such objects are immutable and plugin that wish to modify such objects
- * need to do so using the {@link org.apache.maven.api.services.ProjectManager}
- * service.
+ * need to do so using the {@link org.apache.maven.api.services.ProjectManager
+ * ProjectManager} service.
  * <p>
  * Projects are created using the {@code ProjectBuilder} from a POM file
  * (usually named {@code pom.xml}) on the file system.

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

@@ -30,18 +30,17 @@
  * repository, it attempts to retrieve it from one or more remote
  * repositories.</p>
  *
- * <p>There are several types of remote repositories:<ul>
+ * <p>There are several types of remote repositories:</p><ul>
  * <li><dfn>Central Repository</dfn>: The default remote repository used by Maven. It is a large, publicly accessible repository maintained by the Maven community at https://repo.maven.apache.org/maven2. Most common Java libraries and frameworks are hosted here.</li>
  * <li><dfn>Private Remote Repository</dfn>: Organizations often maintain their own private remote repositories, which may host proprietary or custom-built artifacts that are not available in the central repository. These repositories can be managed using tools like Apache Archiva, Sonatype Nexus, or JFrog Artifactory.</li>
  * <li><dfn>Third-Party Repositories</dfn>: Some projects or organizations host their own remote repositories for distributing specific artifacts that are not available in the central repository. These repositories must be explicitly added to the Maven pom.xml or settings.xml files for Maven to access them.</li></ul>
- * </p>
  *
- * <h3>Repository Configuration</h3>
+ * <h2>Repository Configuration</h2>
  *
- * <p>Repositories can be configured at various levels:<ol>
+ * <p>Repositories can be configured at various levels:</p><ol>
  * <li>POM: Repositories can be specified in the {@code pom.xml} file under the {@code <repositories>} and {@code <pluginRepositories>} sections.</li>
  * <li>Settings: the {@code settings.xml} can be used to provide additional repositories in the three level of settings (user, project, installation).</li>
- * </ol></p>
+ * </ol>
  * <p>By understanding and properly configuring repositories, developers can control where Maven looks for dependencies, manage access to proprietary artifacts, and optimize the build process to ensure consistency and reliability across projects.
  * </p>
  *

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

@@ -24,36 +24,20 @@
 
 /**
  * <p>In Maven, repositories are locations where project artifacts (such as JAR files, POM files, and other
- * resources) are stored and retrieved. There are two primary types of repositories: local repositories and
- * remote repositories.</p>
+ * resources) are stored and retrieved. There are two primary types of repositories:
+ * {@linkplain LocalRepository local repositories} and
+ * {@linkplain RemoteRepository remote repositories}.</p>
  *
- * <h3>Local Repository</h3>
+ * <h2>Repository Resolution Process</h2>
  *
- *
- * <h3>Remote Repository</h3>
- *
- * <p>A <dfn>remote repository</dfn> is a central or distributed location
- * from which Maven can download project dependencies, plugins, and other
- * build artifacts. When Maven cannot find an artifact in the local
- * repository, it attempts to retrieve it from one or more remote
- * repositories.</p>
- *
- * <p>There are several types of remote repositories:<ul>
- * <li><dfn>Central Repository</dfn>: The default remote repository used by Maven. It is a large, publicly accessible repository maintained by the Maven community at https://repo.maven.apache.org/maven2. Most common Java libraries and frameworks are hosted here.</li>
- * <li><dfn>Private Remote Repository</dfn>: Organizations often maintain their own private remote repositories, which may host proprietary or custom-built artifacts that are not available in the central repository. These repositories can be managed using tools like Apache Archiva, Sonatype Nexus, or JFrog Artifactory.</li>
- * <li><dfn>Third-Party Repositories</dfn>: Some projects or organizations host their own remote repositories for distributing specific artifacts that are not available in the central repository. These repositories must be explicitly added to the Maven pom.xml or settings.xml files for Maven to access them.</li></ul>
- * </p>
- *
- * <h3>Repository Resolution Process</h3>
- *
- * <p>When resolving dependencies, Maven follows this order:<ol>
+ * <p>When resolving dependencies, Maven follows this order:</p><ol>
  * <li>Check Local Repository: Maven first checks if the artifact is available in the local repository.</li>
  * <li>Check Remote Repositories: If the artifact is not found locally, Maven queries the configured remote repositories in the order they are listed.</li>
  * <li>Download and Cache: If Maven finds the artifact in a remote repository, it downloads it and stores it in the local repository for future use.</li>
- * </ol></p>
+ * </ol>
  * <p>By caching artifacts in the local repository, Maven minimizes the need to repeatedly download the same artifacts, thus optimizing the build process.</p>
  *
- * <h3>Repository Configuration</h3>
+ * <h2>Repository Configuration</h2>
  *
  * <p>Repositories can be configured at various levels:<ol>
  * <li>POM: Repositories can be specified in the {@code pom.xml} file under the {@code <repositories>} and {@code <pluginRepositories>} sections.</li>

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

@@ -43,20 +43,19 @@
  * </p>
  *
  * <p>
- * The following are key functionalities provided by the Toolchain interface: <ul>
+ * The following are key functionalities provided by the Toolchain interface:</p><ul>
  *   <li>Access to the type of the toolchain (e.g., JDK, compiler).</li>
  *   <li>Retrieval of the specific version of the toolchain.</li>
  *   <li>Configuration of toolchain properties to match the project's requirements.</li>
- * </ul></p>
+ * </ul>
  *
- * <p>
- * Example usage:
+ * <p>Example usage:</p>
  * <pre>
  * Toolchain toolchain = ...; // Obtain a Toolchain instance
  * String type = toolchain.getType(); // Get the type of the toolchain
  * String version = toolchain.getVersion(); // Get the version of the toolchain
  * </pre>
- * </p>
+ *
  *
  * @since 4.0.0
  * @see JavaToolchain

api/maven-api-core/src/main/java/org/apache/maven/api/package-info.java

@@ -18,9 +18,9 @@
  */
 
 /**
- * <h1>Core Maven API</h1>.
+ * <h2>Maven Core API</h2>
  *
- * <h2>Dependency management</h2>
+ * <h3>Dependency management</h3>
  *
  * <p>{@link org.apache.maven.api.ArtifactCoordinate} instances are used to locate artifacts in a repository.
  * Each instance is basically a pointer to a file in the Maven repository, except that the version may not be
@@ -49,7 +49,7 @@
  * <p>{@link org.apache.maven.api.DependencyScope} defines when/how a given dependency will be used by the
  * project.  This includes compile-time only, runtime, test time and various other combinations.</p>
  *
- * <h2>Resolution</h2>
+ * <h3>Resolution</h3>
  *
  * <p><dfn>Version resolution</dfn> is the process of finding, for a given artifact, a list of
  * versions that match the input {@linkplain org.apache.maven.api.VersionConstraint version constraint}
@@ -71,7 +71,8 @@
  * <p><dfn>Dependency resolution</dfn> is the process of collecting dependencies, flattening the result graph,
  * and then resolving the artifacts.</p>
  *
- * <h2>Repositories</h2>
+ * <h3>Repositories</h3>
+ *
  * <p>In Maven, <dfn>{@linkplain org.apache.maven.api.Repository repositories}</dfn> are locations where project artifacts (such as JAR files, POM files, and other
  * resources) are stored and retrieved. There are two primary types of repositories:<ul>
  *     <li><dfn>{@linkplain org.apache.maven.api.LocalRepository local repository}</dfn>: A directory on the developer's machine where Maven caches
@@ -80,14 +81,14 @@
  *     when they are not available locally.</li>
  * </ul>
  *
- * <p>When resolving artifacts, Maven follows this order:<ol>
+ * <p>When resolving artifacts, Maven follows this order:</p><ol>
  * <li>Check Local Repository: Maven first checks if the artifact is available in the local repository.</li>
  * <li>Check Remote Repositories: If the artifact is not found locally, Maven queries the configured remote repositories in the order they are listed.</li>
  * <li>Download and Cache: If Maven finds the artifact in a remote repository, it downloads it and stores it in the local repository for future use.</li>
- * </ol></p>
+ * </ol>
  * <p>By caching artifacts in the local repository, Maven minimizes the need to repeatedly download the same artifacts, thus optimizing the build process.</p>
  *
- * <h2>Projects</h2>
+ * <h3>Projects</h3>
  *
  * <p>{@link org.apache.maven.api.Project} instances are loaded by Maven from the local
  * file system (those projects are usually about to be built) or from the local repository
@@ -96,7 +97,7 @@
  *
  * <p><dfn>Project Object Model</dfn> or <dfn>POM</dfn> refers to the information describing
  * all the information needed to build or consume a project.  Those are usually loaded from
- * a file named <tt>pom.xml</tt> and loaded into a {@link org.apache.maven.api.model.Model Model}
+ * a file named {@code pom.xml} and loaded into a {@link org.apache.maven.api.model.Model Model}
  * instances.</p>
  *
  * <p><dfn>Project aggregation</dfn> allows building several projects together. This is only