This is an automated email from the ASF dual-hosted git repository.

gnodet pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven.git


The following commit(s) were added to refs/heads/master by this push:
     new 81b5ef2acb docs: add missing javadoc to public API classes and methods 
(#13501)
81b5ef2acb is described below

commit 81b5ef2acb5ee40f89fcf563af2053192de182ad
Author: Guillaume Nodet <[email protected]>
AuthorDate: Wed Nov 4 15:33:29 2026 +0100

    docs: add missing javadoc to public API classes and methods (#13501)
    
    * docs: add missing javadoc to public API classes and methods
    
    Add javadoc comments to all public types and methods across the
    api/* modules that were missing documentation.
    
    Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
    
    * docs: add descriptions to stub class-level javadoc
    
    15 classes had javadoc blocks containing only @since tags
    with no actual description. Add a meaningful summary sentence
    to each.
    
    Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
    
    * docs: remove duplicated javadoc on deprecated bridge methods in Exclusion
    
    * docs: revert @Deprecated on XmlNode.merge(3-arg) — to be done in follow-up
    
    ---------
    
    Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>
---
 .../maven/api/cli/logging/AccumulatingLogger.java  |  2 +
 .../java/org/apache/maven/api/DependencyScope.java |  8 +++
 .../main/java/org/apache/maven/api/Exclusion.java  |  6 ++
 .../java/org/apache/maven/api/JavaToolchain.java   | 10 +++
 .../main/java/org/apache/maven/api/PathScope.java  | 10 +++
 .../src/main/java/org/apache/maven/api/Plugin.java | 35 +++++++++
 .../apache/maven/api/plugin/LifecycleProvider.java |  5 ++
 .../main/java/org/apache/maven/api/plugin/Log.java | 52 ++++++++++++++
 .../org/apache/maven/api/plugin/MojoException.java | 10 +++
 .../api/services/ArtifactCoordinatesFactory.java   | 29 ++++++++
 .../ArtifactCoordinatesFactoryRequest.java         | 45 ++++++++++++
 .../api/services/ArtifactDeployerRequest.java      | 12 ++++
 .../apache/maven/api/services/ArtifactFactory.java | 44 ++++++++++++
 .../maven/api/services/ArtifactFactoryRequest.java | 31 +++++++-
 .../api/services/ArtifactInstallerException.java   |  2 +
 .../api/services/ArtifactInstallerRequest.java     |  9 +++
 .../apache/maven/api/services/ArtifactManager.java |  1 +
 .../api/services/ArtifactResolverException.java    |  4 +-
 .../api/services/ArtifactResolverRequest.java      | 17 +++++
 .../org/apache/maven/api/services/BaseRequest.java |  2 +
 .../ChecksumAlgorithmServiceException.java         |  5 ++
 .../api/services/DependencyCoordinatesFactory.java | 37 ++++++++++
 .../DependencyCoordinatesFactoryRequest.java       | 32 +++++++++
 .../maven/api/services/DependencyResolver.java     | 68 ++++++++++++++++++
 .../api/services/DependencyResolverException.java  |  5 ++
 .../api/services/DependencyResolverRequest.java    | 77 ++++++++++++++++++++
 .../maven/api/services/ExtensibleEnumRegistry.java | 13 ++++
 .../apache/maven/api/services/Interpolator.java    |  7 ++
 .../maven/api/services/LanguageRegistry.java       |  5 ++
 .../maven/api/services/LifecycleRegistry.java      | 20 ++++++
 .../java/org/apache/maven/api/services/Lookup.java |  8 +++
 .../apache/maven/api/services/MessageBuilder.java  | 21 ++++++
 .../apache/maven/api/services/ModelBuilder.java    | 30 ++++++++
 .../maven/api/services/ModelBuilderRequest.java    | 62 ++++++++++++++++
 .../maven/api/services/ModelProblemCollector.java  | 82 ++++++++++++++++++++++
 .../maven/api/services/PackagingRegistry.java      |  5 ++
 .../maven/api/services/PathScopeRegistry.java      |  5 ++
 .../apache/maven/api/services/ProjectBuilder.java  |  2 +
 .../maven/api/services/SettingsBuilderRequest.java | 40 +++++++++++
 .../maven/api/services/SettingsBuilderResult.java  |  2 +
 .../api/services/ToolchainsBuilderRequest.java     | 23 ++++++
 .../api/services/ToolchainsBuilderResult.java      |  2 +
 .../api/services/TransportProviderException.java   |  2 +
 .../maven/api/services/VersionRangeResolver.java   |  7 ++
 .../services/VersionRangeResolverException.java    |  2 +
 .../api/services/VersionResolverException.java     |  2 +
 .../maven/api/services/VersionResolverRequest.java | 26 +++++++
 .../maven/api/services/VersionResolverResult.java  | 17 +++++
 .../apache/maven/api/services/xml/Location.java    |  6 ++
 .../apache/maven/api/services/xml/XmlFactory.java  | 79 +++++++++++++++++++++
 .../maven/api/services/xml/XmlReaderException.java |  5 ++
 .../maven/api/services/xml/XmlReaderRequest.java   | 55 +++++++++++++++
 .../maven/api/services/xml/XmlWriterException.java |  5 ++
 .../maven/api/services/xml/XmlWriterRequest.java   | 32 +++++++++
 .../maven/api/services/model/ModelResolver.java    |  7 ++
 .../maven/api/services/model/RootDetector.java     |  6 ++
 .../maven/api/services/model/RootLocator.java      | 19 +++++
 .../apache/maven/api/spi/ModelParserException.java | 16 +++++
 .../maven/api/spi/ModelTransformerException.java   |  5 ++
 .../maven/api/spi/SettingsParserException.java     | 10 +++
 60 files changed, 1184 insertions(+), 2 deletions(-)

diff --git 
a/api/maven-api-cli/src/main/java/org/apache/maven/api/cli/logging/AccumulatingLogger.java
 
b/api/maven-api-cli/src/main/java/org/apache/maven/api/cli/logging/AccumulatingLogger.java
index 013e73a81a..aa4c1d8f96 100644
--- 
a/api/maven-api-cli/src/main/java/org/apache/maven/api/cli/logging/AccumulatingLogger.java
+++ 
b/api/maven-api-cli/src/main/java/org/apache/maven/api/cli/logging/AccumulatingLogger.java
@@ -33,6 +33,7 @@
 public class AccumulatingLogger implements Logger {
     private final AtomicReference<List<Entry>> entries = new 
AtomicReference<>(new CopyOnWriteArrayList<>());
 
+    /** {@inheritDoc} */
     @Override
     public void log(Level level, String message, Throwable error) {
         requireNonNull(level, "level");
@@ -40,6 +41,7 @@ public void log(Level level, String message, Throwable error) 
{
         entries.get().add(new Entry(level, message, error));
     }
 
+    /** {@inheritDoc} */
     @Override
     public List<Entry> drain() {
         return entries.getAndSet(new CopyOnWriteArrayList<>());
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java 
b/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java
index f9f788e003..311f1ec39e 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java
@@ -129,10 +129,18 @@ public String id() {
         return id;
     }
 
+    /**
+     * {@return whether dependencies in this scope are included transitively}.
+     */
     public boolean isTransitive() {
         return transitive;
     }
 
+    /**
+     * {@return whether this scope's {@linkplain #id() id} equals the given 
identifier}.
+     *
+     * @param id the identifier to compare against
+     */
     public boolean is(String id) {
         return id().equals(id);
     }
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/Exclusion.java 
b/api/maven-api-core/src/main/java/org/apache/maven/api/Exclusion.java
index 66b8a7f4c4..586d5718c0 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/Exclusion.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/Exclusion.java
@@ -29,6 +29,9 @@
  */
 @Experimental
 public interface Exclusion {
+    /**
+     * {@return the group identifier of the excluded dependency, or {@code 
null} for a wildcard}.
+     */
     @Nullable
     String groupId();
 
@@ -41,6 +44,9 @@ default String getGroupId() {
         return groupId();
     }
 
+    /**
+     * {@return the artifact identifier of the excluded dependency, or {@code 
null} for a wildcard}.
+     */
     @Nullable
     String artifactId();
 
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/JavaToolchain.java 
b/api/maven-api-core/src/main/java/org/apache/maven/api/JavaToolchain.java
index 5357af9ac4..a64074ea00 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/JavaToolchain.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/JavaToolchain.java
@@ -41,7 +41,17 @@
 @Experimental
 public interface JavaToolchain extends Toolchain {
 
+    /**
+     * Returns the path to the Java home directory for this toolchain.
+     *
+     * @return the Java home path
+     */
     String getJavaHome();
 
+    /**
+     * Returns the Java version provided by this toolchain.
+     *
+     * @return the Java version
+     */
     Version getJavaVersion();
 }
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/PathScope.java 
b/api/maven-api-core/src/main/java/org/apache/maven/api/PathScope.java
index bd8a6f1bf5..34c9158cc6 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/PathScope.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/PathScope.java
@@ -47,9 +47,19 @@
 public interface PathScope extends ExtensibleEnum {
 
     // TODO: what if I simply want all dependencies ?
+    /**
+     * Returns the project scope associated with this path scope.
+     *
+     * @return the project scope, never {@code null}
+     */
     @Nonnull
     ProjectScope projectScope();
 
+    /**
+     * Returns the set of dependency scopes included in this path scope.
+     *
+     * @return the dependency scopes, never {@code null}
+     */
     @Nonnull
     Set<DependencyScope> dependencyScopes();
 
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/Plugin.java 
b/api/maven-api-core/src/main/java/org/apache/maven/api/Plugin.java
index 049f7dd48f..356ec1fe18 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/Plugin.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/Plugin.java
@@ -36,26 +36,61 @@
 @Experimental
 public interface Plugin {
 
+    /**
+     * Returns the POM model element for this plugin.
+     *
+     * @return the plugin model, or {@code null} if not available
+     */
     @Nullable
     org.apache.maven.api.model.Plugin getModel();
 
+    /**
+     * Returns the plugin descriptor containing metadata about goals and 
parameters.
+     *
+     * @return the plugin descriptor, never {@code null}
+     */
     @Nonnull
     PluginDescriptor getDescriptor();
 
+    /**
+     * Returns the custom lifecycles defined by this plugin.
+     *
+     * @return the list of lifecycles, never {@code null}
+     */
     @Nonnull
     List<Lifecycle> getLifecycles();
 
+    /**
+     * Returns the class loader used to load this plugin's classes.
+     *
+     * @return the class loader, never {@code null}
+     */
     @Nonnull
     ClassLoader getClassLoader();
 
+    /**
+     * Returns the artifact for this plugin.
+     *
+     * @return the plugin artifact, or {@code null} if not available
+     */
     @Nullable
     Artifact getArtifact();
 
+    /**
+     * Returns the collection of dependencies for this plugin.
+     *
+     * @return the plugin dependencies, never {@code null}
+     */
     @Nonnull
     default Collection<Dependency> getDependencies() {
         return getDependenciesMap().values();
     }
 
+    /**
+     * Returns the dependencies for this plugin, keyed by their string 
identifier.
+     *
+     * @return the dependency map, never {@code null}
+     */
     @Nonnull
     Map<String, Dependency> getDependenciesMap();
 }
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/LifecycleProvider.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/LifecycleProvider.java
index 1f0d61b2c4..7b39ffdfb2 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/LifecycleProvider.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/LifecycleProvider.java
@@ -37,5 +37,10 @@
 @Consumer
 public interface LifecycleProvider {
 
+    /**
+     * Returns the custom lifecycle definitions provided by this plugin.
+     *
+     * @return the list of lifecycles, never {@code null}
+     */
     List<Lifecycle> getLifecycles();
 }
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/Log.java 
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/Log.java
index 23175d07b1..54eeb10b7e 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/Log.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/Log.java
@@ -137,8 +137,21 @@ default void trace(Supplier<String> content, Throwable 
error) {}
      */
     void debug(Throwable error);
 
+    /**
+     * Sends a lazily-computed message at the <b>debug</b> error level.
+     * The supplier is only evaluated if debug is enabled.
+     *
+     * @param content the message supplier
+     */
     void debug(Supplier<String> content);
 
+    /**
+     * Sends a lazily-computed message (and accompanying exception) at the 
<b>debug</b> error level.
+     * The supplier is only evaluated if debug is enabled.
+     *
+     * @param content the message supplier
+     * @param error the error that caused this log
+     */
     void debug(Supplier<String> content, Throwable error);
 
     /**
@@ -170,8 +183,21 @@ default void trace(Supplier<String> content, Throwable 
error) {}
      */
     void info(Throwable error);
 
+    /**
+     * Sends a lazily-computed message at the <b>info</b> error level.
+     * The supplier is only evaluated if info is enabled.
+     *
+     * @param content the message supplier
+     */
     void info(Supplier<String> content);
 
+    /**
+     * Sends a lazily-computed message (and accompanying exception) at the 
<b>info</b> error level.
+     * The supplier is only evaluated if info is enabled.
+     *
+     * @param content the message supplier
+     * @param error the error that caused this log
+     */
     void info(Supplier<String> content, Throwable error);
 
     /**
@@ -203,8 +229,21 @@ default void trace(Supplier<String> content, Throwable 
error) {}
      */
     void warn(Throwable error);
 
+    /**
+     * Sends a lazily-computed message at the <b>warn</b> error level.
+     * The supplier is only evaluated if warn is enabled.
+     *
+     * @param content the message supplier
+     */
     void warn(Supplier<String> content);
 
+    /**
+     * Sends a lazily-computed message (and accompanying exception) at the 
<b>warn</b> error level.
+     * The supplier is only evaluated if warn is enabled.
+     *
+     * @param content the message supplier
+     * @param error the error that caused this log
+     */
     void warn(Supplier<String> content, Throwable error);
 
     /**
@@ -236,8 +275,21 @@ default void trace(Supplier<String> content, Throwable 
error) {}
      */
     void error(Throwable error);
 
+    /**
+     * Sends a lazily-computed message at the <b>error</b> error level.
+     * The supplier is only evaluated if error is enabled.
+     *
+     * @param content the message supplier
+     */
     void error(Supplier<String> content);
 
+    /**
+     * Sends a lazily-computed message (and accompanying exception) at the 
<b>error</b> error level.
+     * The supplier is only evaluated if error is enabled.
+     *
+     * @param content the message supplier
+     * @param error the error that caused this log
+     */
     void error(Supplier<String> content, Throwable error);
 
     /**
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/MojoException.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/MojoException.java
index 2d4b976cee..e43792a457 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/MojoException.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/MojoException.java
@@ -68,10 +68,20 @@ public MojoException(Throwable cause) {
         super(cause);
     }
 
+    /**
+     * Returns the long message for this exception, providing additional 
detail beyond the short message.
+     *
+     * @return the long message, or {@code null} if not set
+     */
     public String getLongMessage() {
         return longMessage;
     }
 
+    /**
+     * Returns the source of this exception, typically the mojo or component 
that caused it.
+     *
+     * @return the source object, or {@code null} if not set
+     */
     public Object getSource() {
         return source;
     }
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactory.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactory.java
index 8dce1ed48f..3b8c54131d 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactory.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactory.java
@@ -57,12 +57,34 @@ default ArtifactCoordinates create(@Nonnull Session 
session, @Nonnull String coo
         return create(ArtifactCoordinatesFactoryRequest.build(session, 
coordinatesString));
     }
 
+    /**
+     * Creates artifact coordinates from individual components.
+     *
+     * @param session the session
+     * @param groupId the group identifier
+     * @param artifactId the artifact identifier
+     * @param version the version
+     * @param extension the file extension
+     * @return an {@code ArtifactCoordinates}, never {@code null}
+     */
     @Nonnull
     default ArtifactCoordinates create(
             @Nonnull Session session, String groupId, String artifactId, 
String version, String extension) {
         return create(ArtifactCoordinatesFactoryRequest.build(session, 
groupId, artifactId, version, extension));
     }
 
+    /**
+     * Creates artifact coordinates from individual components including 
classifier and type.
+     *
+     * @param session the session
+     * @param groupId the group identifier
+     * @param artifactId the artifact identifier
+     * @param version the version
+     * @param classifier the classifier, may be {@code null}
+     * @param extension the file extension, may be {@code null}
+     * @param type the artifact type, may be {@code null}
+     * @return an {@code ArtifactCoordinates}, never {@code null}
+     */
     @Nonnull
     default ArtifactCoordinates create(
             @Nonnull Session session,
@@ -76,6 +98,13 @@ default ArtifactCoordinates create(
                 session, groupId, artifactId, version, classifier, extension, 
type));
     }
 
+    /**
+     * Creates artifact coordinates from an existing artifact.
+     *
+     * @param session the session
+     * @param artifact the artifact to derive coordinates from
+     * @return an {@code ArtifactCoordinates}, never {@code null}
+     */
     @Nonnull
     default ArtifactCoordinates create(@Nonnull Session session, Artifact 
artifact) {
         return create(ArtifactCoordinatesFactoryRequest.build(
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactoryRequest.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactoryRequest.java
index 0c7ae82767..8b5dc26f7d 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactoryRequest.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactoryRequest.java
@@ -38,20 +38,37 @@
 @Immutable
 public interface ArtifactCoordinatesFactoryRequest extends Request<Session> {
 
+    /** @return the group identifier */
     String getGroupId();
 
+    /** @return the artifact identifier */
     String getArtifactId();
 
+    /** @return the version */
     String getVersion();
 
+    /** @return the classifier, may be {@code null} */
     String getClassifier();
 
+    /** @return the file extension, may be {@code null} */
     String getExtension();
 
+    /** @return the artifact type, may be {@code null} */
     String getType();
 
+    /** @return the coordinate string in the format {@code 
groupId:artifactId[:extension[:classifier]]:version}, may be {@code null} */
     String getCoordinatesString();
 
+    /**
+     * Builds a request from individual coordinate components.
+     *
+     * @param session the session
+     * @param groupId the group identifier
+     * @param artifactId the artifact identifier
+     * @param version the version
+     * @param extension the file extension
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static ArtifactCoordinatesFactoryRequest build(
             @Nonnull Session session, String groupId, String artifactId, 
String version, String extension) {
@@ -64,6 +81,18 @@ static ArtifactCoordinatesFactoryRequest build(
                 .build();
     }
 
+    /**
+     * Builds a request from individual coordinate components including 
classifier and type.
+     *
+     * @param session the session
+     * @param groupId the group identifier
+     * @param artifactId the artifact identifier
+     * @param version the version
+     * @param classifier the classifier
+     * @param extension the file extension
+     * @param type the artifact type
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static ArtifactCoordinatesFactoryRequest build(
             @Nonnull Session session,
@@ -84,6 +113,14 @@ static ArtifactCoordinatesFactoryRequest build(
                 .build();
     }
 
+    /**
+     * Builds a request from a coordinate string formatted as
+     * {@code <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>}.
+     *
+     * @param session the session
+     * @param coordinateString the coordinate string
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static ArtifactCoordinatesFactoryRequest build(@Nonnull Session session, 
@Nonnull String coordinateString) {
         return ArtifactCoordinatesFactoryRequest.builder()
@@ -92,6 +129,13 @@ static ArtifactCoordinatesFactoryRequest build(@Nonnull 
Session session, @Nonnul
                 .build();
     }
 
+    /**
+     * Builds a request from existing artifact coordinates.
+     *
+     * @param session the session
+     * @param coordinates the artifact coordinates
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static ArtifactCoordinatesFactoryRequest build(@Nonnull Session session, 
@Nonnull ArtifactCoordinates coordinates) {
         return ArtifactCoordinatesFactoryRequest.builder()
@@ -104,6 +148,7 @@ static ArtifactCoordinatesFactoryRequest build(@Nonnull 
Session session, @Nonnul
                 .build();
     }
 
+    /** @return a new builder instance */
     static ArtifactFactoryRequestBuilder builder() {
         return new ArtifactFactoryRequestBuilder();
     }
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactDeployerRequest.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactDeployerRequest.java
index 8d54d882c0..dacb2cf765 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactDeployerRequest.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactDeployerRequest.java
@@ -41,19 +41,31 @@
 @Immutable
 public interface ArtifactDeployerRequest extends Request<Session> {
 
+    /** @return the remote repository to deploy to, never {@code null} */
     @Nonnull
     RemoteRepository getRepository();
 
+    /** @return the artifacts to deploy, never {@code null} */
     @Nonnull
     Collection<ProducedArtifact> getArtifacts();
 
+    /** @return the number of times to retry a failed deployment */
     int getRetryFailedDeploymentCount();
 
+    /** @return a new builder instance */
     @Nonnull
     static ArtifactDeployerRequestBuilder builder() {
         return new ArtifactDeployerRequestBuilder();
     }
 
+    /**
+     * Builds a request to deploy artifacts to a remote repository.
+     *
+     * @param session the session
+     * @param repository the target remote repository
+     * @param artifacts the artifacts to deploy
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static ArtifactDeployerRequest build(
             @Nonnull Session session,
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactory.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactory.java
index da77fc2d52..ae0f127494 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactory.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactory.java
@@ -43,12 +43,34 @@ public interface ArtifactFactory extends Service {
     @Nonnull
     Artifact create(@Nonnull ArtifactFactoryRequest request);
 
+    /**
+     * Creates an artifact from individual components.
+     *
+     * @param session the session
+     * @param groupId the group identifier
+     * @param artifactId the artifact identifier
+     * @param version the version
+     * @param extension the file extension
+     * @return an {@code Artifact}, never {@code null}
+     */
     @Nonnull
     default Artifact create(
             @Nonnull Session session, String groupId, String artifactId, 
String version, String extension) {
         return create(ArtifactFactoryRequest.build(session, groupId, 
artifactId, version, extension));
     }
 
+    /**
+     * Creates an artifact from individual components including classifier and 
type.
+     *
+     * @param session the session
+     * @param groupId the group identifier
+     * @param artifactId the artifact identifier
+     * @param version the version
+     * @param classifier the classifier, may be {@code null}
+     * @param extension the file extension, may be {@code null}
+     * @param type the artifact type, may be {@code null}
+     * @return an {@code Artifact}, never {@code null}
+     */
     @Nonnull
     default Artifact create(
             @Nonnull Session session,
@@ -71,12 +93,34 @@ default Artifact create(
     @Nonnull
     ProducedArtifact createProduced(@Nonnull ArtifactFactoryRequest request);
 
+    /**
+     * Creates a produced artifact from individual components.
+     *
+     * @param session the session
+     * @param groupId the group identifier
+     * @param artifactId the artifact identifier
+     * @param version the version
+     * @param extension the file extension
+     * @return a {@code ProducedArtifact}, never {@code null}
+     */
     @Nonnull
     default ProducedArtifact createProduced(
             @Nonnull Session session, String groupId, String artifactId, 
String version, String extension) {
         return createProduced(ArtifactFactoryRequest.build(session, groupId, 
artifactId, version, extension));
     }
 
+    /**
+     * Creates a produced artifact from individual components including 
classifier and type.
+     *
+     * @param session the session
+     * @param groupId the group identifier
+     * @param artifactId the artifact identifier
+     * @param version the version
+     * @param classifier the classifier, may be {@code null}
+     * @param extension the file extension, may be {@code null}
+     * @param type the artifact type, may be {@code null}
+     * @return a {@code ProducedArtifact}, never {@code null}
+     */
     @Nonnull
     default ProducedArtifact createProduced(
             @Nonnull Session session,
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactoryRequest.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactoryRequest.java
index 0d97922374..1205b0d4d1 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactoryRequest.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactoryRequest.java
@@ -30,7 +30,7 @@
 import static java.util.Objects.requireNonNull;
 
 /**
- *
+ * Request for creating an {@link org.apache.maven.api.Artifact} from 
individual coordinate components.
  *
  * @since 4.0.0
  */
@@ -38,18 +38,34 @@
 @Immutable
 public interface ArtifactFactoryRequest extends Request<Session> {
 
+    /** @return the group identifier */
     String getGroupId();
 
+    /** @return the artifact identifier */
     String getArtifactId();
 
+    /** @return the version */
     String getVersion();
 
+    /** @return the classifier, may be {@code null} */
     String getClassifier();
 
+    /** @return the file extension, may be {@code null} */
     String getExtension();
 
+    /** @return the artifact type, may be {@code null} */
     String getType();
 
+    /**
+     * Builds a request from individual components.
+     *
+     * @param session the session
+     * @param groupId the group identifier
+     * @param artifactId the artifact identifier
+     * @param version the version
+     * @param extension the file extension
+     * @return a new request
+     */
     static ArtifactFactoryRequest build(
             Session session, String groupId, String artifactId, String 
version, String extension) {
         return ArtifactFactoryRequest.builder()
@@ -61,6 +77,18 @@ static ArtifactFactoryRequest build(
                 .build();
     }
 
+    /**
+     * Builds a request from individual components including classifier and 
type.
+     *
+     * @param session the session
+     * @param groupId the group identifier
+     * @param artifactId the artifact identifier
+     * @param version the version
+     * @param classifier the classifier
+     * @param extension the file extension
+     * @param type the artifact type
+     * @return a new request
+     */
     static ArtifactFactoryRequest build(
             Session session,
             String groupId,
@@ -80,6 +108,7 @@ static ArtifactFactoryRequest build(
                 .build();
     }
 
+    /** @return a new builder instance */
     static ArtifactFactoryRequestBuilder builder() {
         return new ArtifactFactoryRequestBuilder();
     }
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerException.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerException.java
index c683928810..d419bf611e 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerException.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerException.java
@@ -21,6 +21,8 @@
 import org.apache.maven.api.annotations.Experimental;
 
 /**
+ * Exception thrown when installing artifacts into the local repository fails.
+ *
  * @since 4.0.0
  */
 @Experimental
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerRequest.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerRequest.java
index 6f5a57e0ea..1363ac4978 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerRequest.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerRequest.java
@@ -42,14 +42,23 @@
 @Immutable
 public interface ArtifactInstallerRequest extends Request<Session> {
 
+    /** @return the artifacts to install, never {@code null} */
     @Nonnull
     Collection<ProducedArtifact> getArtifacts();
 
+    /** @return a new builder instance */
     @Nonnull
     static ArtifactInstallerRequestBuilder builder() {
         return new ArtifactInstallerRequestBuilder();
     }
 
+    /**
+     * Builds a request to install artifacts in the local repository.
+     *
+     * @param session the session
+     * @param artifacts the artifacts to install
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static ArtifactInstallerRequest build(Session session, 
Collection<ProducedArtifact> artifacts) {
         return builder()
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactManager.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactManager.java
index 8eb1739eaf..1e69393e03 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactManager.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactManager.java
@@ -28,6 +28,7 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
+ * Service for associating file system paths with artifacts within the current 
session.
  *
  * @since 4.0.0
  */
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverException.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverException.java
index 22d5af16f3..7b64b0152a 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverException.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverException.java
@@ -21,7 +21,8 @@
 import org.apache.maven.api.annotations.Experimental;
 
 /**
- *
+ * Exception thrown when artifact resolution fails, carrying the partial
+ * {@link ArtifactResolverResult} with details about the failure.
  *
  * @since 4.0.0
  */
@@ -40,6 +41,7 @@ public ArtifactResolverException(String message, Exception e, 
ArtifactResolverRe
         this.result = result;
     }
 
+    /** @return the resolution result containing detailed information about 
the failure */
     public ArtifactResolverResult getResult() {
         return result;
     }
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverRequest.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverRequest.java
index 7e832a95e4..c99a2ca2fe 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverRequest.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverRequest.java
@@ -42,14 +42,23 @@
 @Immutable
 public interface ArtifactResolverRequest extends RepositoryAwareRequest {
 
+    /** @return the coordinates of the artifacts to resolve, never {@code 
null} */
     @Nonnull
     Collection<? extends ArtifactCoordinates> getCoordinates();
 
+    /** @return a new builder instance */
     @Nonnull
     static ArtifactResolverRequestBuilder builder() {
         return new ArtifactResolverRequestBuilder();
     }
 
+    /**
+     * Builds a request to resolve artifacts from their coordinates.
+     *
+     * @param session the session
+     * @param coordinates the artifact coordinates to resolve
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static ArtifactResolverRequest build(
             @Nonnull Session session, @Nonnull Collection<? extends 
ArtifactCoordinates> coordinates) {
@@ -59,6 +68,14 @@ static ArtifactResolverRequest build(
                 .build();
     }
 
+    /**
+     * Builds a request to resolve artifacts from specific repositories.
+     *
+     * @param session the session
+     * @param coordinates the artifact coordinates to resolve
+     * @param repositories the remote repositories to resolve from
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static ArtifactResolverRequest build(
             @Nonnull Session session,
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/BaseRequest.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/BaseRequest.java
index b5e338466a..e01b2d5bec 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/BaseRequest.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/BaseRequest.java
@@ -44,12 +44,14 @@ protected BaseRequest(@Nonnull S session, RequestTrace 
trace) {
         this.trace = trace;
     }
 
+    /** {@inheritDoc} */
     @Nonnull
     @Override
     public S getSession() {
         return session;
     }
 
+    /** {@inheritDoc} */
     @Override
     public RequestTrace getTrace() {
         return trace;
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ChecksumAlgorithmServiceException.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ChecksumAlgorithmServiceException.java
index 7aaed5632f..3ad15b3f8a 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ChecksumAlgorithmServiceException.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ChecksumAlgorithmServiceException.java
@@ -20,6 +20,11 @@
 
 import org.apache.maven.api.annotations.Experimental;
 
+/**
+ * Exception thrown when an error occurs in the checksum algorithm service.
+ *
+ * @since 4.0.0
+ */
 @Experimental
 public class ChecksumAlgorithmServiceException extends MavenException {
 
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactory.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactory.java
index 29b06c45d3..1decb21938 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactory.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactory.java
@@ -29,6 +29,8 @@
 import org.apache.maven.api.model.ReportPlugin;
 
 /**
+ * Service for creating {@link org.apache.maven.api.DependencyCoordinates} 
instances
+ * from requests, model dependencies, plugins, or artifact coordinates.
  *
  * @since 4.0.0
  */
@@ -47,17 +49,38 @@ public interface DependencyCoordinatesFactory extends 
Service {
     @Nonnull
     DependencyCoordinates create(@Nonnull DependencyCoordinatesFactoryRequest 
request);
 
+    /**
+     * Creates dependency coordinates from artifact coordinates.
+     *
+     * @param session the session
+     * @param coordinates the artifact coordinates
+     * @return a new {@link DependencyCoordinates}, never {@code null}
+     */
     @Nonnull
     default DependencyCoordinates create(@Nonnull Session session, @Nonnull 
ArtifactCoordinates coordinates) {
         return create(DependencyCoordinatesFactoryRequest.build(session, 
coordinates));
     }
 
+    /**
+     * Creates dependency coordinates from an existing dependency.
+     *
+     * @param session the session
+     * @param dependency the dependency
+     * @return a new {@link DependencyCoordinates}, never {@code null}
+     */
     @Nonnull
     default DependencyCoordinates create(
             @Nonnull Session session, @Nonnull org.apache.maven.api.Dependency 
dependency) {
         return create(DependencyCoordinatesFactoryRequest.build(session, 
dependency));
     }
 
+    /**
+     * Creates dependency coordinates from a model dependency.
+     *
+     * @param session the session
+     * @param dependency the model dependency
+     * @return a new {@link DependencyCoordinates}, never {@code null}
+     */
     @Nonnull
     default DependencyCoordinates create(@Nonnull Session session, Dependency 
dependency) {
         return create(DependencyCoordinatesFactoryRequest.build(
@@ -70,6 +93,13 @@ default DependencyCoordinates create(@Nonnull Session 
session, Dependency depend
                 dependency.getType()));
     }
 
+    /**
+     * Creates dependency coordinates from a plugin model.
+     *
+     * @param session the session
+     * @param plugin the plugin
+     * @return a new {@link DependencyCoordinates}, never {@code null}
+     */
     @Nonnull
     default DependencyCoordinates create(@Nonnull Session session, Plugin 
plugin) {
         // TODO: hard coded string
@@ -77,6 +107,13 @@ default DependencyCoordinates create(@Nonnull Session 
session, Plugin plugin) {
                 session, plugin.getGroupId(), plugin.getArtifactId(), 
plugin.getVersion(), null, null, "maven-plugin"));
     }
 
+    /**
+     * Creates dependency coordinates from a report plugin model.
+     *
+     * @param session the session
+     * @param reportPlugin the report plugin
+     * @return a new {@link DependencyCoordinates}, never {@code null}
+     */
     @Nonnull
     default DependencyCoordinates create(@Nonnull Session session, 
ReportPlugin reportPlugin) {
         // TODO: hard coded string
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactoryRequest.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactoryRequest.java
index 70d4d02f52..283b5c7272 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactoryRequest.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactoryRequest.java
@@ -36,6 +36,8 @@
 import static java.util.Objects.requireNonNull;
 
 /**
+ * Request for creating {@link org.apache.maven.api.DependencyCoordinates}, 
extending
+ * {@link ArtifactCoordinatesFactoryRequest} with scope, optionality, and 
exclusion information.
  *
  * @since 4.0.0
  */
@@ -43,13 +45,28 @@
 @Immutable
 public interface DependencyCoordinatesFactoryRequest extends 
ArtifactCoordinatesFactoryRequest {
 
+    /** @return the dependency scope, may be {@code null} */
     String getScope();
 
+    /** @return whether this dependency is optional */
     boolean isOptional();
 
+    /** @return the dependency exclusions, never {@code null} */
     @Nonnull
     Collection<Exclusion> getExclusions();
 
+    /**
+     * Builds a request from individual components.
+     *
+     * @param session the session
+     * @param groupId the group identifier
+     * @param artifactId the artifact identifier
+     * @param version the version
+     * @param classifier the classifier
+     * @param extension the file extension
+     * @param type the artifact type
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static DependencyCoordinatesFactoryRequest build(
             @Nonnull Session session,
@@ -70,6 +87,13 @@ static DependencyCoordinatesFactoryRequest build(
                 .build();
     }
 
+    /**
+     * Builds a request from existing artifact coordinates.
+     *
+     * @param session the session
+     * @param coordinates the artifact coordinates
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static DependencyCoordinatesFactoryRequest build(
             @Nonnull Session session, @Nonnull ArtifactCoordinates 
coordinates) {
@@ -84,6 +108,13 @@ static DependencyCoordinatesFactoryRequest build(
                 .build();
     }
 
+    /**
+     * Builds a request from an existing dependency.
+     *
+     * @param session the session
+     * @param dependency the dependency to derive coordinates from
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static DependencyCoordinatesFactoryRequest build(@Nonnull Session session, 
@Nonnull Dependency dependency) {
         return builder()
@@ -99,6 +130,7 @@ static DependencyCoordinatesFactoryRequest build(@Nonnull 
Session session, @Nonn
                 .build();
     }
 
+    /** @return a new builder instance */
     @Nonnull
     static DependencyCoordinatesFactoryRequestBuilder builder() {
         return new DependencyCoordinatesFactoryRequestBuilder();
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolver.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolver.java
index 0473cce537..24c1c15be5 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolver.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolver.java
@@ -133,6 +133,15 @@ default DependencyResolverResult collect(@Nonnull 
DependencyResolverRequest requ
     List<Node> flatten(@Nonnull Session session, @Nonnull Node node, @Nullable 
PathScope scope)
             throws DependencyResolverException;
 
+    /**
+     * Flattens the dependency tree of a project for the given path scope.
+     *
+     * @param session the session
+     * @param project the project
+     * @param scope the path scope
+     * @return the flattened result, never {@code null}
+     * @throws DependencyResolverException if the dependency tree could not be 
flattened
+     */
     @Nonnull
     default DependencyResolverResult flatten(
             @Nonnull Session session, @Nonnull Project project, @Nonnull 
PathScope scope) {
@@ -140,6 +149,14 @@ default DependencyResolverResult flatten(
                 session, DependencyResolverRequest.RequestType.FLATTEN, 
project, scope));
     }
 
+    /**
+     * Flattens the dependency tree described by the request.
+     *
+     * @param request the dependency resolver request with type {@link 
DependencyResolverRequest.RequestType#FLATTEN}
+     * @return the flattened result, never {@code null}
+     * @throws IllegalArgumentException if the request type is not {@code 
FLATTEN}
+     * @throws DependencyResolverException if the dependency tree could not be 
flattened
+     */
     @Nonnull
     default DependencyResolverResult flatten(@Nonnull 
DependencyResolverRequest request) {
         if (request.getRequestType() != 
DependencyResolverRequest.RequestType.FLATTEN) {
@@ -148,12 +165,29 @@ default DependencyResolverResult flatten(@Nonnull 
DependencyResolverRequest requ
         return resolve(request);
     }
 
+    /**
+     * Resolves the dependencies of a project for the default runtime scope.
+     *
+     * @param session the session
+     * @param project the project
+     * @return the resolution result, never {@code null}
+     * @throws DependencyResolverException if dependency resolution fails
+     */
     @Nonnull
     default DependencyResolverResult resolve(@Nonnull Session session, 
@Nonnull Project project) {
         return resolve(
                 DependencyResolverRequest.build(session, 
DependencyResolverRequest.RequestType.RESOLVE, project));
     }
 
+    /**
+     * Resolves the dependencies of a project for the given path scope.
+     *
+     * @param session the session
+     * @param project the project
+     * @param scope the path scope
+     * @return the resolution result, never {@code null}
+     * @throws DependencyResolverException if dependency resolution fails
+     */
     @Nonnull
     default DependencyResolverResult resolve(
             @Nonnull Session session, @Nonnull Project project, @Nonnull 
PathScope scope) {
@@ -161,12 +195,29 @@ default DependencyResolverResult resolve(
                 session, DependencyResolverRequest.RequestType.RESOLVE, 
project, scope));
     }
 
+    /**
+     * Resolves a single dependency for the default runtime scope.
+     *
+     * @param session the session
+     * @param dependency the dependency coordinates
+     * @return the resolution result, never {@code null}
+     * @throws DependencyResolverException if dependency resolution fails
+     */
     @Nonnull
     default DependencyResolverResult resolve(@Nonnull Session session, 
@Nonnull DependencyCoordinates dependency) {
         return resolve(
                 DependencyResolverRequest.build(session, 
DependencyResolverRequest.RequestType.RESOLVE, dependency));
     }
 
+    /**
+     * Resolves a single dependency for the given path scope.
+     *
+     * @param session the session
+     * @param dependency the dependency coordinates
+     * @param scope the path scope
+     * @return the resolution result, never {@code null}
+     * @throws DependencyResolverException if dependency resolution fails
+     */
     @Nonnull
     default DependencyResolverResult resolve(
             @Nonnull Session session, @Nonnull DependencyCoordinates 
dependency, @Nonnull PathScope scope) {
@@ -174,6 +225,14 @@ default DependencyResolverResult resolve(
                 session, DependencyResolverRequest.RequestType.RESOLVE, 
dependency, scope));
     }
 
+    /**
+     * Resolves a list of dependencies for the default runtime scope.
+     *
+     * @param session the session
+     * @param dependencies the dependency coordinates
+     * @return the resolution result, never {@code null}
+     * @throws DependencyResolverException if dependency resolution fails
+     */
     @Nonnull
     default DependencyResolverResult resolve(
             @Nonnull Session session, @Nonnull List<DependencyCoordinates> 
dependencies) {
@@ -181,6 +240,15 @@ default DependencyResolverResult resolve(
                 DependencyResolverRequest.build(session, 
DependencyResolverRequest.RequestType.RESOLVE, dependencies));
     }
 
+    /**
+     * Resolves a list of dependencies for the given path scope.
+     *
+     * @param session the session
+     * @param dependencies the dependency coordinates
+     * @param scope the path scope
+     * @return the resolution result, never {@code null}
+     * @throws DependencyResolverException if dependency resolution fails
+     */
     @Nonnull
     default DependencyResolverResult resolve(
             @Nonnull Session session, @Nonnull List<DependencyCoordinates> 
dependencies, @Nonnull PathScope scope) {
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverException.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverException.java
index a26a88c6f7..e6b57056a0 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverException.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverException.java
@@ -20,6 +20,11 @@
 
 import org.apache.maven.api.annotations.Experimental;
 
+/**
+ * Exception thrown when dependency resolution fails.
+ *
+ * @since 4.0.0
+ */
 @Experimental
 public class DependencyResolverException extends MavenException {
 
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverRequest.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverRequest.java
index 5be250824d..f84327763b 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverRequest.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverRequest.java
@@ -63,26 +63,34 @@ enum RequestType {
         RESOLVE
     }
 
+    /** @return the type of request (collect, flatten, or resolve) */
     @Nonnull
     RequestType getRequestType();
 
+    /** @return the project whose dependencies should be resolved, or empty if 
not project-based */
     @Nonnull
     Optional<Project> getProject();
 
+    /** @return the root artifact for the dependency graph, or empty */
     @Nonnull
     Optional<Artifact> getRootArtifact();
 
+    /** @return the root dependency coordinates, or empty */
     @Nonnull
     Optional<DependencyCoordinates> getRoot();
 
+    /** @return the direct dependencies, never {@code null} */
     @Nonnull
     Collection<DependencyCoordinates> getDependencies();
 
+    /** @return the managed dependencies for version and scope management, 
never {@code null} */
     @Nonnull
     Collection<DependencyCoordinates> getManagedDependencies();
 
+    /** @return whether to produce a verbose dependency graph */
     boolean getVerbose();
 
+    /** @return the path scope for dependency resolution */
     @Nonnull
     PathScope getPathScope();
 
@@ -119,16 +127,34 @@ enum RequestType {
     @Nullable
     Version getTargetVersion();
 
+    /** @return a new builder instance */
     @Nonnull
     static DependencyResolverRequestBuilder builder() {
         return new DependencyResolverRequestBuilder();
     }
 
+    /**
+     * Builds a request for the given artifact using the default runtime scope.
+     *
+     * @param session the session
+     * @param requestType the request type
+     * @param rootArtifact the root artifact
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static DependencyResolverRequest build(Session session, RequestType 
requestType, Artifact rootArtifact) {
         return build(session, requestType, rootArtifact, 
PathScope.MAIN_RUNTIME);
     }
 
+    /**
+     * Builds a request for the given artifact and path scope.
+     *
+     * @param session the session
+     * @param requestType the request type
+     * @param rootArtifact the root artifact
+     * @param scope the path scope
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static DependencyResolverRequest build(
             Session session, RequestType requestType, Artifact rootArtifact, 
PathScope scope) {
@@ -140,11 +166,28 @@ static DependencyResolverRequest build(
                 .build();
     }
 
+    /**
+     * Builds a request for the given project using the default runtime scope.
+     *
+     * @param session the session
+     * @param requestType the request type
+     * @param project the project
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static DependencyResolverRequest build(Session session, RequestType 
requestType, Project project) {
         return build(session, requestType, project, PathScope.MAIN_RUNTIME);
     }
 
+    /**
+     * Builds a request for the given project and path scope.
+     *
+     * @param session the session
+     * @param requestType the request type
+     * @param project the project
+     * @param scope the path scope
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static DependencyResolverRequest build(Session session, RequestType 
requestType, Project project, PathScope scope) {
         return new DependencyResolverRequestBuilder()
@@ -155,11 +198,28 @@ static DependencyResolverRequest build(Session session, 
RequestType requestType,
                 .build();
     }
 
+    /**
+     * Builds a request for the given dependency using the default runtime 
scope.
+     *
+     * @param session the session
+     * @param requestType the request type
+     * @param dependency the root dependency coordinates
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static DependencyResolverRequest build(Session session, RequestType 
requestType, DependencyCoordinates dependency) {
         return build(session, requestType, dependency, PathScope.MAIN_RUNTIME);
     }
 
+    /**
+     * Builds a request for the given dependency and path scope.
+     *
+     * @param session the session
+     * @param requestType the request type
+     * @param dependency the root dependency coordinates
+     * @param scope the path scope
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static DependencyResolverRequest build(
             Session session, RequestType requestType, DependencyCoordinates 
dependency, PathScope scope) {
@@ -171,12 +231,29 @@ static DependencyResolverRequest build(
                 .build();
     }
 
+    /**
+     * Builds a request for the given dependencies using the default runtime 
scope.
+     *
+     * @param session the session
+     * @param requestType the request type
+     * @param dependencies the dependency coordinates
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static DependencyResolverRequest build(
             Session session, RequestType requestType, 
List<DependencyCoordinates> dependencies) {
         return build(session, requestType, dependencies, 
PathScope.MAIN_RUNTIME);
     }
 
+    /**
+     * Builds a request for the given dependencies and path scope.
+     *
+     * @param session the session
+     * @param requestType the request type
+     * @param dependencies the dependency coordinates
+     * @param scope the path scope
+     * @return a new request, never {@code null}
+     */
     @Nonnull
     static DependencyResolverRequest build(
             Session session, RequestType requestType, 
List<DependencyCoordinates> dependencies, PathScope scope) {
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ExtensibleEnumRegistry.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ExtensibleEnumRegistry.java
index 06d9726cac..8588a29a9b 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ExtensibleEnumRegistry.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ExtensibleEnumRegistry.java
@@ -35,9 +35,22 @@
  * @since 4.0.0
  */
 public interface ExtensibleEnumRegistry<T extends ExtensibleEnum> extends 
Service {
+    /**
+     * Looks up an extensible enum value by its identifier.
+     *
+     * @param id the identifier of the enum value to look up
+     * @return an {@code Optional} containing the enum value, or empty if not 
found
+     */
     @Nonnull
     Optional<T> lookup(@Nonnull String id);
 
+    /**
+     * Looks up an extensible enum value by its identifier, throwing if not 
found.
+     *
+     * @param id the identifier of the enum value to look up
+     * @return the enum value
+     * @throws IllegalArgumentException if no value is registered with the 
given id
+     */
     @Nonnull
     default T require(@Nonnull String id) {
         return lookup(id).orElseThrow(() -> new 
IllegalArgumentException("Unknown extensible enum value '" + id + "'"));
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/Interpolator.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/Interpolator.java
index 86e7e74d38..4418d570c2 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/Interpolator.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/Interpolator.java
@@ -159,6 +159,13 @@ static UnaryOperator<String> chain(Collection<? extends 
UnaryOperator<String>> f
         };
     }
 
+    /**
+     * Creates a composite function from a varargs array of functions.
+     *
+     * @param functions the functions to chain
+     * @return a function that applies each function in order until a non-null 
result is found
+     * @see #chain(Collection)
+     */
     @SafeVarargs
     static UnaryOperator<String> chain(UnaryOperator<String>... functions) {
         return chain(List.of(functions));
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/LanguageRegistry.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/LanguageRegistry.java
index d2f0f09331..4bd0b7f3f4 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/LanguageRegistry.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/LanguageRegistry.java
@@ -20,4 +20,9 @@
 
 import org.apache.maven.api.Language;
 
+/**
+ * Registry for {@link Language} extensible enum values.
+ *
+ * @since 4.0.0
+ */
 public interface LanguageRegistry extends ExtensibleEnumRegistry<Language> {}
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/LifecycleRegistry.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/LifecycleRegistry.java
index 55efc16ebc..881efa891f 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/LifecycleRegistry.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/LifecycleRegistry.java
@@ -24,11 +24,31 @@
 
 import org.apache.maven.api.Lifecycle;
 
+/**
+ * Registry for {@link Lifecycle} extensible enum values.
+ * <p>
+ * In addition to the standard registry lookup operations, this interface 
provides
+ * iteration over all registered lifecycles and computation of the ordered 
phase list
+ * for a given lifecycle.
+ *
+ * @since 4.0.0
+ */
 public interface LifecycleRegistry extends ExtensibleEnumRegistry<Lifecycle>, 
Iterable<Lifecycle> {
 
+    /**
+     * Returns a sequential stream of all registered lifecycles.
+     *
+     * @return a stream of lifecycles
+     */
     default Stream<Lifecycle> stream() {
         return StreamSupport.stream(spliterator(), false);
     }
 
+    /**
+     * Computes the ordered list of phase names for the given lifecycle.
+     *
+     * @param lifecycle the lifecycle whose phases should be computed
+     * @return the ordered list of phase names
+     */
     List<String> computePhases(Lifecycle lifecycle);
 }
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/Lookup.java 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/Lookup.java
index c80c2ed10e..da3a2395d2 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/Lookup.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/Lookup.java
@@ -25,6 +25,14 @@
 import org.apache.maven.api.Service;
 import org.apache.maven.api.annotations.Nonnull;
 
+/**
+ * Service for looking up components from the dependency injection container.
+ * <p>
+ * Provides methods to retrieve single components, optional components, and
+ * collections of components by their type and optional name qualifier.
+ *
+ * @since 4.0.0
+ */
 public interface Lookup extends Service {
     /**
      * Performs a lookup for given typed component.
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/MessageBuilder.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/MessageBuilder.java
index ae0d249c33..8884b96e16 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/MessageBuilder.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/MessageBuilder.java
@@ -149,27 +149,48 @@ default MessageBuilder project(Object message) {
         return style("." + Constants.MAVEN_STYLE_PROJECT_NAME + ":-" + 
Constants.MAVEN_STYLE_PROJECT_DEFAULT, message);
     }
 
+    /**
+     * Append message content with the given style applied, then reset the 
style.
+     *
+     * @param style the style definition to apply
+     * @param message the message to append
+     * @return the current builder
+     */
     @Nonnull
     default MessageBuilder style(String style, Object message) {
         return style(style).a(message).resetStyle();
     }
 
+    /**
+     * Apply the given style to subsequent appended content.
+     *
+     * @param style the style definition to apply
+     * @return the current builder
+     */
     MessageBuilder style(String style);
 
+    /**
+     * Reset the current style back to the default.
+     *
+     * @return the current builder
+     */
     MessageBuilder resetStyle();
 
     //
     // message building methods modelled after Ansi methods
     //
 
+    /** {@inheritDoc} */
     @Nonnull
     @Override
     MessageBuilder append(CharSequence cs);
 
+    /** {@inheritDoc} */
     @Nonnull
     @Override
     MessageBuilder append(CharSequence cs, int start, int end);
 
+    /** {@inheritDoc} */
     @Nonnull
     @Override
     MessageBuilder append(char c);
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilder.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilder.java
index c98c5ace62..4e676260af 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilder.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilder.java
@@ -23,6 +23,14 @@
 import org.apache.maven.api.Service;
 import org.apache.maven.api.model.Model;
 
+/**
+ * Service for building Maven project models from POM files or other sources.
+ * <p>
+ * The model builder processes raw POM files through the full Maven model 
building pipeline,
+ * including inheritance assembly, profile activation, interpolation, and 
validation.
+ *
+ * @since 4.0.0
+ */
 public interface ModelBuilder extends Service {
 
     String MODEL_VERSION_4_0_0 = "4.0.0";
@@ -33,10 +41,25 @@ public interface ModelBuilder extends Service {
 
     List<String> KNOWN_MODEL_VERSIONS = List.of(MODEL_VERSION_4_0_0, 
MODEL_VERSION_4_1_0, MODEL_VERSION_4_2_0);
 
+    /**
+     * Creates a new model builder session for building one or more models.
+     *
+     * @return a new model builder session
+     */
     ModelBuilderSession newSession();
 
+    /**
+     * A session for building models, allowing multiple builds to share state.
+     */
     interface ModelBuilderSession {
 
+        /**
+         * Builds the effective model from the given request.
+         *
+         * @param request the model builder request
+         * @return the model builder result
+         * @throws ModelBuilderException if the model cannot be built
+         */
         ModelBuilderResult build(ModelBuilderRequest request) throws 
ModelBuilderException;
 
         /**
@@ -67,5 +90,12 @@ default ModelBuilderResult validate(ModelBuilderRequest 
request) throws ModelBui
         }
     }
 
+    /**
+     * Builds a raw model from the given request without applying inheritance 
or interpolation.
+     *
+     * @param request the model builder request
+     * @return the raw model
+     * @throws ModelBuilderException if the raw model cannot be built
+     */
     Model buildRawModel(ModelBuilderRequest request) throws 
ModelBuilderException;
 }
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilderRequest.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilderRequest.java
index 496715802c..a0160992db 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilderRequest.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilderRequest.java
@@ -95,14 +95,34 @@ enum RepositoryMerging {
         REQUEST_DOMINANT,
     }
 
+    /**
+     * Gets the source from which the model should be built.
+     *
+     * @return the model source
+     */
     @Nonnull
     ModelSource getSource();
 
+    /**
+     * Gets the type of build request.
+     *
+     * @return the request type
+     */
     @Nonnull
     RequestType getRequestType();
 
+    /**
+     * Returns whether input location tracking is enabled for the model.
+     *
+     * @return {@code true} if location tracking is enabled
+     */
     boolean isLocationTracking();
 
+    /**
+     * Returns whether the build should recursively process sub-projects.
+     *
+     * @return {@code true} if recursive processing is enabled
+     */
     boolean isRecursive();
 
     /**
@@ -137,12 +157,29 @@ enum RepositoryMerging {
     @Nonnull
     Map<String, String> getUserProperties();
 
+    /**
+     * Gets the strategy for merging repositories from the POM with those from 
the request.
+     *
+     * @return the repository merging strategy
+     */
     @Nonnull
     RepositoryMerging getRepositoryMerging();
 
+    /**
+     * Gets the model transformer used to inject lifecycle bindings.
+     *
+     * @return the lifecycle bindings injector, or {@code null} if none
+     */
     @Nullable
     ModelTransformer getLifecycleBindingsInjector();
 
+    /**
+     * Creates a new request by copying an existing request and replacing the 
source.
+     *
+     * @param request the original request to copy
+     * @param source the new model source
+     * @return the new request
+     */
     @Nonnull
     static ModelBuilderRequest build(@Nonnull ModelBuilderRequest request, 
@Nonnull ModelSource source) {
         return builder(requireNonNull(request, "request cannot be null"))
@@ -150,6 +187,13 @@ static ModelBuilderRequest build(@Nonnull 
ModelBuilderRequest request, @Nonnull
                 .build();
     }
 
+    /**
+     * Creates a new request for the given session and source.
+     *
+     * @param session the session
+     * @param source the model source
+     * @return the new request
+     */
     @Nonnull
     static ModelBuilderRequest build(@Nonnull Session session, @Nonnull 
ModelSource source) {
         return builder()
@@ -158,6 +202,13 @@ static ModelBuilderRequest build(@Nonnull Session session, 
@Nonnull ModelSource
                 .build();
     }
 
+    /**
+     * Creates a new request for the given session and POM path.
+     *
+     * @param session the session
+     * @param path the path to the POM file
+     * @return the new request
+     */
     @Nonnull
     static ModelBuilderRequest build(@Nonnull Session session, @Nonnull Path 
path) {
         return builder()
@@ -166,11 +217,22 @@ static ModelBuilderRequest build(@Nonnull Session 
session, @Nonnull Path path) {
                 .build();
     }
 
+    /**
+     * Creates a new builder for constructing a {@code ModelBuilderRequest}.
+     *
+     * @return a new builder
+     */
     @Nonnull
     static ModelBuilderRequestBuilder builder() {
         return new ModelBuilderRequestBuilder();
     }
 
+    /**
+     * Creates a new builder initialized from the given request.
+     *
+     * @param request the request to copy values from
+     * @return a new builder pre-populated with the request's values
+     */
     @Nonnull
     static ModelBuilderRequestBuilder builder(ModelBuilderRequest request) {
         return new ModelBuilderRequestBuilder(request);
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblemCollector.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblemCollector.java
index 66c1fcc31e..fc8cf04edf 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblemCollector.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblemCollector.java
@@ -31,30 +31,77 @@
  */
 public interface ModelProblemCollector {
 
+    /**
+     * Returns the underlying problem collector.
+     *
+     * @return the problem collector
+     */
     ProblemCollector<ModelProblem> getProblemCollector();
 
+    /**
+     * Returns {@code true} if any problems with {@link 
BuilderProblem.Severity#ERROR} or higher have been collected.
+     *
+     * @return {@code true} if errors exist
+     */
     default boolean hasErrors() {
         return getProblemCollector().hasErrorProblems();
     }
 
+    /**
+     * Returns {@code true} if any problems with {@link 
BuilderProblem.Severity#FATAL} have been collected.
+     *
+     * @return {@code true} if fatal errors exist
+     */
     default boolean hasFatalErrors() {
         return getProblemCollector().hasFatalProblems();
     }
 
+    /**
+     * Adds a problem with the given severity, version, and message.
+     *
+     * @param severity the problem severity
+     * @param version the model version
+     * @param message the problem message
+     */
     default void add(BuilderProblem.Severity severity, ModelProblem.Version 
version, String message) {
         add(severity, version, message, null, null);
     }
 
+    /**
+     * Adds a problem with the given severity, version, message, and location.
+     *
+     * @param severity the problem severity
+     * @param version the model version
+     * @param message the problem message
+     * @param location the input location where the problem occurred
+     */
     default void add(
             BuilderProblem.Severity severity, ModelProblem.Version version, 
String message, InputLocation location) {
         add(severity, version, message, location, null);
     }
 
+    /**
+     * Adds a problem with the given severity, version, message, and exception.
+     *
+     * @param severity the problem severity
+     * @param version the model version
+     * @param message the problem message
+     * @param exception the exception that caused the problem
+     */
     default void add(
             BuilderProblem.Severity severity, ModelProblem.Version version, 
String message, Exception exception) {
         add(severity, version, message, null, exception);
     }
 
+    /**
+     * Adds a problem with the given severity, version, message, location, and 
exception.
+     *
+     * @param severity the problem severity
+     * @param version the model version
+     * @param message the problem message
+     * @param location the input location where the problem occurred, or 
{@code null}
+     * @param exception the exception that caused the problem, or {@code null}
+     */
     void add(
             BuilderProblem.Severity severity,
             ModelProblem.Version version,
@@ -62,19 +109,54 @@ void add(
             InputLocation location,
             Exception exception);
 
+    /**
+     * Adds a pre-constructed model problem directly.
+     *
+     * @param problem the model problem to add
+     */
     default void add(ModelProblem problem) {
         getProblemCollector().reportProblem(problem);
     }
 
+    /**
+     * Creates a {@link ModelBuilderException} from the collected problems.
+     *
+     * @return a new exception summarizing the collected problems
+     */
     ModelBuilderException newModelBuilderException();
 
+    /**
+     * Sets the source hint used to provide context for subsequently collected 
problems.
+     *
+     * @param location the source location string
+     */
     void setSource(String location);
 
+    /**
+     * Sets the source hint from a model's coordinates.
+     *
+     * @param model the model to derive the source hint from
+     */
     void setSource(Model model);
 
+    /**
+     * Gets the current source hint.
+     *
+     * @return the source hint string
+     */
     String getSource();
 
+    /**
+     * Sets the root model being built.
+     *
+     * @param model the root model
+     */
     void setRootModel(Model model);
 
+    /**
+     * Gets the root model being built.
+     *
+     * @return the root model, or {@code null} if not yet set
+     */
     Model getRootModel();
 }
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/PackagingRegistry.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/PackagingRegistry.java
index e114e26640..d26d732ff0 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/PackagingRegistry.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/PackagingRegistry.java
@@ -20,4 +20,9 @@
 
 import org.apache.maven.api.Packaging;
 
+/**
+ * Registry for {@link Packaging} extensible enum values.
+ *
+ * @since 4.0.0
+ */
 public interface PackagingRegistry extends ExtensibleEnumRegistry<Packaging> {}
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/PathScopeRegistry.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/PathScopeRegistry.java
index 06b5d59647..b196036b98 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/PathScopeRegistry.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/PathScopeRegistry.java
@@ -20,4 +20,9 @@
 
 import org.apache.maven.api.PathScope;
 
+/**
+ * Registry for {@link PathScope} extensible enum values.
+ *
+ * @since 4.0.0
+ */
 public interface PathScopeRegistry extends ExtensibleEnumRegistry<PathScope> {}
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilder.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilder.java
index 518033b601..d8d06524a4 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilder.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilder.java
@@ -26,6 +26,8 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
+ * Service for building {@link org.apache.maven.api.Project} instances from 
POM files or other sources.
+ *
  * @since 4.0.0
  */
 @Experimental
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderRequest.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderRequest.java
index 1ab8a9a15b..2c0946282e 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderRequest.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderRequest.java
@@ -72,6 +72,14 @@ public interface SettingsBuilderRequest extends 
Request<ProtoSession> {
     @Nonnull
     Optional<UnaryOperator<String>> getInterpolationSource();
 
+    /**
+     * Creates a request from installation and user settings sources.
+     *
+     * @param session the session
+     * @param installationSettingsSource the installation settings source
+     * @param userSettingsSource the user settings source
+     * @return the new request
+     */
     @Nonnull
     static SettingsBuilderRequest build(
             @Nonnull ProtoSession session,
@@ -80,12 +88,29 @@ static SettingsBuilderRequest build(
         return build(session, installationSettingsSource, null, 
userSettingsSource);
     }
 
+    /**
+     * Creates a request from installation and user settings paths.
+     *
+     * @param session the session
+     * @param installationSettingsPath the installation settings path
+     * @param userSettingsPath the user settings path
+     * @return the new request
+     */
     @Nonnull
     static SettingsBuilderRequest build(
             @Nonnull ProtoSession session, @Nonnull Path 
installationSettingsPath, @Nonnull Path userSettingsPath) {
         return build(session, Sources.fromPath(installationSettingsPath), 
null, Sources.fromPath(userSettingsPath));
     }
 
+    /**
+     * Creates a request from installation, project, and user settings sources.
+     *
+     * @param session the session
+     * @param installationSettingsSource the installation settings source, or 
{@code null}
+     * @param projectSettingsSource the project settings source, or {@code 
null}
+     * @param userSettingsSource the user settings source, or {@code null}
+     * @return the new request
+     */
     @Nonnull
     static SettingsBuilderRequest build(
             @Nonnull ProtoSession session,
@@ -100,6 +125,16 @@ static SettingsBuilderRequest build(
                 .build();
     }
 
+    /**
+     * Creates a request from installation, project, and user settings paths.
+     * Paths that do not exist are treated as absent.
+     *
+     * @param session the session
+     * @param installationSettingsPath the installation settings path, or 
{@code null}
+     * @param projectSettingsPath the project settings path, or {@code null}
+     * @param userSettingsPath the user settings path, or {@code null}
+     * @return the new request
+     */
     @Nonnull
     static SettingsBuilderRequest build(
             @Nonnull ProtoSession session,
@@ -123,6 +158,11 @@ static SettingsBuilderRequest build(
                 .build();
     }
 
+    /**
+     * Creates a new builder for constructing a {@code SettingsBuilderRequest}.
+     *
+     * @return a new builder
+     */
     @Nonnull
     static SettingsBuilderRequestBuilder builder() {
         return new SettingsBuilderRequestBuilder();
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderResult.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderResult.java
index 37b6213da2..881f5ed662 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderResult.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderResult.java
@@ -23,6 +23,8 @@
 import org.apache.maven.api.settings.Settings;
 
 /**
+ * Result of building the effective Maven settings, providing access to the 
assembled
+ * {@link org.apache.maven.api.settings.Settings} and any problems encountered 
during the build.
  *
  * @since 4.0.0
  */
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderRequest.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderRequest.java
index 0257ae6760..31c90d5044 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderRequest.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderRequest.java
@@ -32,6 +32,7 @@
 import static java.util.Objects.requireNonNull;
 
 /**
+ * Request for building the effective toolchains from installation and 
user-level toolchain sources.
  *
  * @since 4.0.0
  */
@@ -54,6 +55,14 @@ public interface ToolchainsBuilderRequest extends 
Request<ProtoSession> {
     @Nonnull
     Optional<Source> getUserToolchainsSource();
 
+    /**
+     * Creates a request from installation and user toolchains sources.
+     *
+     * @param session the session
+     * @param installationToolchainsFile the installation toolchains source, 
or {@code null}
+     * @param userToolchainsSource the user toolchains source, or {@code null}
+     * @return the new request
+     */
     @Nonnull
     static ToolchainsBuilderRequest build(
             @Nonnull ProtoSession session,
@@ -66,6 +75,15 @@ static ToolchainsBuilderRequest build(
                 .build();
     }
 
+    /**
+     * Creates a request from installation and user toolchains paths.
+     * Paths that do not exist are treated as absent.
+     *
+     * @param session the session
+     * @param installationToolchainsFile the installation toolchains path, or 
{@code null}
+     * @param userToolchainsPath the user toolchains path, or {@code null}
+     * @return the new request
+     */
     @Nonnull
     static ToolchainsBuilderRequest build(
             @Nonnull ProtoSession session,
@@ -84,6 +102,11 @@ static ToolchainsBuilderRequest build(
                 .build();
     }
 
+    /**
+     * Creates a new builder for constructing a {@code 
ToolchainsBuilderRequest}.
+     *
+     * @return a new builder
+     */
     @Nonnull
     static ToolchainsBuilderRequestBuilder builder() {
         return new ToolchainsBuilderRequestBuilder();
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderResult.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderResult.java
index 3cf06a7397..b4d24592a9 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderResult.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderResult.java
@@ -23,6 +23,8 @@
 import org.apache.maven.api.toolchain.PersistedToolchains;
 
 /**
+ * Result of building the effective toolchains, providing access to the 
assembled
+ * {@link org.apache.maven.api.toolchain.PersistedToolchains} and any problems 
encountered.
  *
  * @since 4.0.0
  */
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/TransportProviderException.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/TransportProviderException.java
index c78fa37e24..c8226074ea 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/TransportProviderException.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/TransportProviderException.java
@@ -22,6 +22,8 @@
 import org.apache.maven.api.annotations.Experimental;
 
 /**
+ * Exception thrown when a transport provider encounters an error during 
remote repository access.
+ *
  * @since 4.0.0
  */
 @Experimental
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolver.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolver.java
index aec999dd28..81f2147d10 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolver.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolver.java
@@ -81,6 +81,13 @@ default VersionRangeResolverResult resolve(
         return resolve(VersionRangeResolverRequest.build(session, 
artifactCoordinates, repositories));
     }
 
+    /**
+     * Expands a version range to a list of matching versions using the given 
request.
+     *
+     * @param request the version range resolver request
+     * @return the version range resolution result
+     * @throws VersionRangeResolverException if the version range could not be 
resolved
+     */
     @Nonnull
     VersionRangeResolverResult resolve(@Nonnull VersionRangeResolverRequest 
request)
             throws VersionRangeResolverException;
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverException.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverException.java
index dd0746844f..1f6c19b7e3 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverException.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverException.java
@@ -22,6 +22,8 @@
 import org.apache.maven.api.annotations.Experimental;
 
 /**
+ * Exception thrown when resolving a version range against available 
repositories fails.
+ *
  * @since 4.0.0
  */
 @Experimental
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverException.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverException.java
index 6eb5b0989c..73add57ed0 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverException.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverException.java
@@ -22,6 +22,8 @@
 import org.apache.maven.api.annotations.Experimental;
 
 /**
+ * Exception thrown when resolving a meta-version (such as {@code LATEST} or 
{@code RELEASE}) fails.
+ *
  * @since 4.0.0
  */
 @Experimental
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverRequest.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverRequest.java
index b510dcc2de..1ae301c710 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverRequest.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverRequest.java
@@ -32,15 +32,28 @@
 import static java.util.Objects.requireNonNull;
 
 /**
+ * Request for resolving a meta-version of an artifact to a concrete version.
  *
  * @since 4.0.0
  */
 @Experimental
 public interface VersionResolverRequest extends RepositoryAwareRequest {
 
+    /**
+     * Gets the artifact coordinates whose version should be resolved.
+     *
+     * @return the artifact coordinates
+     */
     @Nonnull
     ArtifactCoordinates getArtifactCoordinates();
 
+    /**
+     * Creates a request for the given session and artifact coordinates.
+     *
+     * @param session the session
+     * @param artifactCoordinates the artifact coordinates
+     * @return the new request
+     */
     @Nonnull
     static VersionResolverRequest build(@Nonnull Session session, @Nonnull 
ArtifactCoordinates artifactCoordinates) {
         return builder()
@@ -49,6 +62,14 @@ static VersionResolverRequest build(@Nonnull Session 
session, @Nonnull ArtifactC
                 .build();
     }
 
+    /**
+     * Creates a request for the given session, artifact coordinates, and 
repositories.
+     *
+     * @param session the session
+     * @param artifactCoordinates the artifact coordinates
+     * @param repositories the repositories to use, or {@code null} to use the 
session's repositories
+     * @return the new request
+     */
     @Nonnull
     static VersionResolverRequest build(
             @Nonnull Session session,
@@ -61,6 +82,11 @@ static VersionResolverRequest build(
                 .build();
     }
 
+    /**
+     * Creates a new builder for constructing a {@code VersionResolverRequest}.
+     *
+     * @return a new builder
+     */
     @Nonnull
     static VersionResolverRequestBuilder builder() {
         return new VersionResolverRequestBuilder();
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverResult.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverResult.java
index 5b9e61b40d..d1adda355e 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverResult.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverResult.java
@@ -27,18 +27,35 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
+ * Result of resolving a meta-version, providing the concrete resolved version
+ * and the repository it was resolved from.
  *
  * @since 4.0.0
  */
 @Experimental
 public interface VersionResolverResult extends Result<VersionResolverRequest> {
 
+    /**
+     * Gets the exceptions that occurred during version resolution.
+     *
+     * @return the list of exceptions, never {@code null}
+     */
     @Nonnull
     List<Exception> getExceptions();
 
+    /**
+     * Gets the resolved version.
+     *
+     * @return the resolved version
+     */
     @Nonnull
     Version getVersion();
 
+    /**
+     * Gets the repository from which the version was resolved.
+     *
+     * @return an optional containing the repository, or empty if unknown
+     */
     @Nonnull
     Optional<Repository> getRepository();
 }
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/Location.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/Location.java
index a79d9fcb8d..2dadc303d2 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/Location.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/Location.java
@@ -18,6 +18,12 @@
  */
 package org.apache.maven.api.services.xml;
 
+/**
+ * Represents a location in an XML document, providing line number, column 
number,
+ * and character offset information for diagnostics and error reporting.
+ *
+ * @since 4.0.0
+ */
 public interface Location {
 
     /**
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java
index 733e70b282..363852198d 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java
@@ -39,43 +39,109 @@
 @Experimental
 public interface XmlFactory<T> extends Service {
 
+    /**
+     * Reads an object from the specified path using strict parsing.
+     *
+     * @param path the path to read from
+     * @return the parsed object
+     * @throws XmlReaderException if an error occurs during parsing
+     */
     @Nonnull
     default T read(@Nonnull Path path) throws XmlReaderException {
         return read(path, true);
     }
 
+    /**
+     * Reads an object from the specified path.
+     *
+     * @param path the path to read from
+     * @param strict whether to enforce strict parsing
+     * @return the parsed object
+     * @throws XmlReaderException if an error occurs during parsing
+     */
     @Nonnull
     default T read(@Nonnull Path path, boolean strict) throws 
XmlReaderException {
         return 
read(XmlReaderRequest.builder().path(path).strict(strict).build());
     }
 
+    /**
+     * Reads an object from the specified input stream using strict parsing.
+     *
+     * @param input the input stream to read from
+     * @return the parsed object
+     * @throws XmlReaderException if an error occurs during parsing
+     */
     @Nonnull
     default T read(@Nonnull InputStream input) throws XmlReaderException {
         return read(input, true);
     }
 
+    /**
+     * Reads an object from the specified input stream.
+     *
+     * @param input the input stream to read from
+     * @param strict whether to enforce strict parsing
+     * @return the parsed object
+     * @throws XmlReaderException if an error occurs during parsing
+     */
     @Nonnull
     default T read(@Nonnull InputStream input, boolean strict) throws 
XmlReaderException {
         return 
read(XmlReaderRequest.builder().inputStream(input).strict(strict).build());
     }
 
+    /**
+     * Reads an object from the specified reader using strict parsing.
+     *
+     * @param reader the reader to read from
+     * @return the parsed object
+     * @throws XmlReaderException if an error occurs during parsing
+     */
     @Nonnull
     default T read(@Nonnull Reader reader) throws XmlReaderException {
         return read(reader, true);
     }
 
+    /**
+     * Reads an object from the specified reader.
+     *
+     * @param reader the reader to read from
+     * @param strict whether to enforce strict parsing
+     * @return the parsed object
+     * @throws XmlReaderException if an error occurs during parsing
+     */
     @Nonnull
     default T read(@Nonnull Reader reader, boolean strict) throws 
XmlReaderException {
         return 
read(XmlReaderRequest.builder().reader(reader).strict(strict).build());
     }
 
+    /**
+     * Reads an object using the specified request.
+     *
+     * @param request the reader request containing the input source and 
options
+     * @return the parsed object
+     * @throws XmlReaderException if an error occurs during parsing
+     */
     @Nonnull
     T read(@Nonnull XmlReaderRequest request) throws XmlReaderException;
 
+    /**
+     * Writes the given content to the specified path.
+     *
+     * @param content the object to write
+     * @param path the path to write to
+     * @throws XmlWriterException if an error occurs during writing
+     */
     default void write(@Nonnull T content, @Nonnull Path path) throws 
XmlWriterException {
         
write(XmlWriterRequest.<T>builder().content(content).path(path).build());
     }
 
+    /**
+     * Writes the given content to the specified output stream.
+     *
+     * @param content the object to write
+     * @param outputStream the output stream to write to
+     * @throws XmlWriterException if an error occurs during writing
+     */
     default void write(@Nonnull T content, @Nonnull OutputStream outputStream) 
throws XmlWriterException {
         write(XmlWriterRequest.<T>builder()
                 .content(content)
@@ -83,10 +149,23 @@ default void write(@Nonnull T content, @Nonnull 
OutputStream outputStream) throw
                 .build());
     }
 
+    /**
+     * Writes the given content to the specified writer.
+     *
+     * @param content the object to write
+     * @param writer the writer to write to
+     * @throws XmlWriterException if an error occurs during writing
+     */
     default void write(@Nonnull T content, @Nonnull Writer writer) throws 
XmlWriterException {
         
write(XmlWriterRequest.<T>builder().content(content).writer(writer).build());
     }
 
+    /**
+     * Writes an object using the specified request.
+     *
+     * @param request the writer request containing the output target and 
content
+     * @throws XmlWriterException if an error occurs during writing
+     */
     void write(@Nonnull XmlWriterRequest<T> request) throws XmlWriterException;
 
     /**
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderException.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderException.java
index f631752159..5c0471d52d 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderException.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderException.java
@@ -40,6 +40,11 @@ public XmlReaderException(String message, Location location, 
Exception e) {
         this.location = location;
     }
 
+    /**
+     * Returns the location in the XML document where the error occurred.
+     *
+     * @return the error location, or {@code null} if not available
+     */
     public Location getLocation() {
         return location;
     }
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderRequest.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderRequest.java
index 07fd999b9f..14896a3f0e 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderRequest.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderRequest.java
@@ -38,32 +38,82 @@
 @Immutable
 public interface XmlReaderRequest {
 
+    /**
+     * Returns the path to the XML file to read, or {@code null} if another 
input source is used.
+     *
+     * @return the file path, or {@code null}
+     */
     @Nullable
     Path getPath();
 
+    /**
+     * Returns the root directory for resolving relative paths, or {@code 
null} if not set.
+     *
+     * @return the root directory, or {@code null}
+     */
     @Nullable
     Path getRootDirectory();
 
+    /**
+     * Returns the URL to read the XML from, or {@code null} if another input 
source is used.
+     *
+     * @return the URL, or {@code null}
+     */
     @Nullable
     URL getURL();
 
+    /**
+     * Returns the input stream to read the XML from, or {@code null} if 
another input source is used.
+     *
+     * @return the input stream, or {@code null}
+     */
     @Nullable
     InputStream getInputStream();
 
+    /**
+     * Returns the reader to read the XML from, or {@code null} if another 
input source is used.
+     *
+     * @return the reader, or {@code null}
+     */
     @Nullable
     Reader getReader();
 
+    /**
+     * Returns the transformer to apply during parsing, or {@code null} if 
none is set.
+     *
+     * @return the transformer, or {@code null}
+     */
     @Nullable
     Transformer getTransformer();
 
+    /**
+     * Returns whether strict parsing should be enforced.
+     *
+     * @return {@code true} if strict parsing is enabled
+     */
     boolean isStrict();
 
+    /**
+     * Returns the identifier of the model being parsed, used for error 
reporting.
+     *
+     * @return the model identifier, or {@code null}
+     */
     @Nullable
     String getModelId();
 
+    /**
+     * Returns the location description used for error reporting.
+     *
+     * @return the location string, or {@code null}
+     */
     @Nullable
     String getLocation();
 
+    /**
+     * Returns whether default XML entities should be added during parsing.
+     *
+     * @return {@code true} if default entities should be added
+     */
     boolean isAddDefaultEntities();
 
     /**
@@ -92,6 +142,11 @@ interface Transformer {
         String transform(String source, String fieldName);
     }
 
+    /**
+     * Creates a new builder for constructing {@code XmlReaderRequest} 
instances.
+     *
+     * @return a new builder
+     */
     @Nonnull
     static XmlReaderRequestBuilder builder() {
         return new XmlReaderRequestBuilder();
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterException.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterException.java
index 69852d375f..0ea0ad349f 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterException.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterException.java
@@ -40,6 +40,11 @@ public XmlWriterException(String message, Location location, 
Exception e) {
         this.location = location;
     }
 
+    /**
+     * Returns the location in the XML document where the error occurred.
+     *
+     * @return the error location, or {@code null} if not available
+     */
     public Location getLocation() {
         return location;
     }
diff --git 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterRequest.java
 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterRequest.java
index 46ee89c8cf..f0bca5a128 100644
--- 
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterRequest.java
+++ 
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterRequest.java
@@ -36,21 +36,53 @@
 @Experimental
 public interface XmlWriterRequest<T> {
 
+    /**
+     * Returns the path to write to, or {@code null} if another output target 
is used.
+     *
+     * @return the file path, or {@code null}
+     */
     @Nullable
     Path getPath();
 
+    /**
+     * Returns the output stream to write to, or {@code null} if another 
output target is used.
+     *
+     * @return the output stream, or {@code null}
+     */
     @Nullable
     OutputStream getOutputStream();
 
+    /**
+     * Returns the writer to write to, or {@code null} if another output 
target is used.
+     *
+     * @return the writer, or {@code null}
+     */
     @Nullable
     Writer getWriter();
 
+    /**
+     * Returns the content object to be written as XML.
+     *
+     * @return the content to write
+     */
     @Nonnull
     T getContent();
 
+    /**
+     * Returns the formatter for rendering input location information in the 
output,
+     * or {@code null} if location information should not be included.
+     *
+     * @return the input location formatter, or {@code null}
+     */
     @Nullable
     Function<Object, String> getInputLocationFormatter();
 
+    /**
+     * Creates a new builder for constructing {@code XmlWriterRequest} 
instances.
+     *
+     * @param <T> the content type
+     * @return a new builder
+     */
     static <T> XmlWriterRequestBuilder<T> builder() {
         return new XmlWriterRequestBuilder<>();
     }
diff --git 
a/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/ModelResolver.java
 
b/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/ModelResolver.java
index 58cd0aef0f..bab8c4d787 100644
--- 
a/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/ModelResolver.java
+++ 
b/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/ModelResolver.java
@@ -77,6 +77,13 @@ ModelSource resolveModel(
             @Nonnull AtomicReference<Dependency> modified)
             throws ModelResolverException;
 
+    /**
+     * Resolves a POM for the specified coordinates.
+     *
+     * @param request the resolution request containing group, artifact, and 
version coordinates
+     * @return the resolution result containing the model source and resolved 
version
+     * @throws ModelResolverException if the POM could not be resolved
+     */
     @Nonnull
     ModelResolverResult resolveModel(@Nonnull ModelResolverRequest request) 
throws ModelResolverException;
 
diff --git 
a/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootDetector.java
 
b/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootDetector.java
index 2c341d2709..7033eca3c4 100644
--- 
a/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootDetector.java
+++ 
b/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootDetector.java
@@ -28,5 +28,11 @@
  * @since 4.0.0
  */
 public interface RootDetector extends Service {
+    /**
+     * Checks whether the given directory is a project root directory.
+     *
+     * @param dir the directory to check
+     * @return {@code true} if the directory is a root directory, {@code 
false} otherwise
+     */
     boolean isRootDirectory(Path dir);
 }
diff --git 
a/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootLocator.java
 
b/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootLocator.java
index 739c279db8..d47e23748b 100644
--- 
a/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootLocator.java
+++ 
b/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootLocator.java
@@ -43,12 +43,31 @@ public interface RootLocator extends Service {
             + "Create a .mvn directory in the root directory or add the 
root=\"true\""
             + " attribute on the root project's model to identify it.";
 
+    /**
+     * Finds the root directory by searching from the given base directory 
upwards.
+     *
+     * @param basedir the starting directory for the search
+     * @return the root directory path, or {@code null} if none was found
+     */
     @Nullable
     Path findRoot(@Nonnull Path basedir);
 
+    /**
+     * Finds the root directory by searching from the given base directory 
upwards,
+     * throwing an exception if no root can be found.
+     *
+     * @param basedir the starting directory for the search
+     * @return the root directory path, never {@code null}
+     * @throws IllegalStateException if no root directory can be found
+     */
     @Nonnull
     Path findMandatoryRoot(@Nonnull Path basedir);
 
+    /**
+     * Returns the error message to use when no root directory can be found.
+     *
+     * @return the error message, never {@code null}
+     */
     @Nonnull
     default String getNoRootMessage() {
         return UNABLE_TO_FIND_ROOT_PROJECT_MESSAGE;
diff --git 
a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParserException.java
 
b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParserException.java
index 4520f0650b..db16f7d4b1 100644
--- 
a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParserException.java
+++ 
b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParserException.java
@@ -21,6 +21,12 @@
 import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.services.MavenException;
 
+/**
+ * Exception thrown when a model parser encounters an error while reading a 
POM or other model source.
+ * Carries optional line and column number information to help locate the 
error.
+ *
+ * @since 4.0.0
+ */
 @Experimental
 public class ModelParserException extends MavenException {
 
@@ -56,10 +62,20 @@ public ModelParserException(Throwable cause) {
         this(null, cause);
     }
 
+    /**
+     * Returns the one-based line number where the error occurred, or {@code 
-1} if unknown.
+     *
+     * @return the line number
+     */
     public int getLineNumber() {
         return lineNumber;
     }
 
+    /**
+     * Returns the one-based column number where the error occurred, or {@code 
-1} if unknown.
+     *
+     * @return the column number
+     */
     public int getColumnNumber() {
         return columnNumber;
     }
diff --git 
a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelTransformerException.java
 
b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelTransformerException.java
index d2f8443826..a06acac628 100644
--- 
a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelTransformerException.java
+++ 
b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelTransformerException.java
@@ -21,6 +21,11 @@
 import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.services.MavenException;
 
+/**
+ * Exception thrown when a model transformation fails.
+ *
+ * @since 4.0.0
+ */
 @Experimental
 public class ModelTransformerException extends MavenException {
 
diff --git 
a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/SettingsParserException.java
 
b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/SettingsParserException.java
index 4981fa5ba6..fc2daebd2c 100644
--- 
a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/SettingsParserException.java
+++ 
b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/SettingsParserException.java
@@ -74,10 +74,20 @@ private static String messageOrDefault(String message, 
Throwable cause) {
         return "Unknown settings parsing error";
     }
 
+    /**
+     * Returns the one-based line number where the error occurred, or {@code 
-1} if unknown.
+     *
+     * @return the line number
+     */
     public int getLineNumber() {
         return lineNumber;
     }
 
+    /**
+     * Returns the one-based column number where the error occurred, or {@code 
-1} if unknown.
+     *
+     * @return the column number
+     */
     public int getColumnNumber() {
         return columnNumber;
     }

Reply via email to