From 456890d40bd63af5036b8db31c4e5b50532f48ee Mon Sep 17 00:00:00 2001
From: Guillaume Nodet <gnodet@gmail.com>
Date: Thu, 29 Feb 2024 00:54:53 +0100
Subject: [PATCH] Missing annotations on api (#1428)

---
 .../java/org/apache/maven/api/Dependency.java |  8 +++
 .../org/apache/maven/api/ExtensibleEnum.java  |  4 ++
 .../org/apache/maven/api/MojoExecution.java   |  2 +
 .../java/org/apache/maven/api/Plugin.java     |  2 +
 .../apache/maven/api/RemoteRepository.java    |  2 +
 .../java/org/apache/maven/api/Service.java    |  1 +
 .../java/org/apache/maven/api/Session.java    | 58 +++++++++++++++++--
 .../maven/api/plugin/LifecycleProvider.java   |  2 +
 .../java/org/apache/maven/api/plugin/Log.java |  2 +
 .../api/services/ExtensibleEnumRegistry.java  |  5 +-
 .../api/services/ProjectScopeRegistry.java    |  4 ++
 .../maven/api/services/SettingsBuilder.java   |  4 ++
 .../api/services/SettingsBuilderResult.java   |  6 ++
 .../maven/api/services/SuperPomProvider.java  |  2 +
 .../maven/api/services/ToolchainsBuilder.java |  2 +
 .../services/ToolchainsBuilderRequest.java    |  6 ++
 .../api/services/ToolchainsBuilderResult.java |  6 ++
 .../api/services/VersionRangeResolver.java    |  2 +
 .../services/VersionRangeResolverRequest.java |  4 ++
 .../services/VersionRangeResolverResult.java  |  4 ++
 .../maven/api/services/VersionResolver.java   |  2 +
 .../api/services/VersionResolverRequest.java  |  4 ++
 .../api/services/VersionResolverResult.java   |  4 ++
 .../maven/api/annotations/Consumer.java       |  2 +-
 .../maven/api/spi/ExtensibleEnumProvider.java | 16 +++++
 .../maven/api/spi/LanguageProvider.java       |  7 +++
 .../org/apache/maven/api/spi/ModelParser.java |  5 ++
 .../maven/api/spi/PathScopeProvider.java      |  7 +++
 .../maven/api/spi/ProjectScopeProvider.java   |  7 +++
 .../maven/api/spi/PropertyContributor.java    |  4 ++
 .../apache/maven/api/spi/TypeProvider.java    |  7 +++
 31 files changed, 183 insertions(+), 8 deletions(-)

diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/Dependency.java b/api/maven-api-core/src/main/java/org/apache/maven/api/Dependency.java
index d0906581b6..8af8b69fb9 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/Dependency.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/Dependency.java
@@ -18,8 +18,16 @@
  */
 package org.apache.maven.api;
 
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Immutable;
 import org.apache.maven.api.annotations.Nonnull;
 
+/**
+ *
+ * @since 4.0.0
+ */
+@Experimental
+@Immutable
 public interface Dependency extends Artifact {
 
     /**
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/ExtensibleEnum.java b/api/maven-api-core/src/main/java/org/apache/maven/api/ExtensibleEnum.java
index 87d80075dd..fc1412a36a 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/ExtensibleEnum.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/ExtensibleEnum.java
@@ -18,12 +18,16 @@
  */
 package org.apache.maven.api;
 
+import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
  * Implementation must have {@code equals()} and {@code hashCode()} implemented, so implementations of this interface
  * can be used as keys.
+ *
+ * @since 4.0.0
  */
+@Experimental
 public interface ExtensibleEnum {
 
     /**
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/MojoExecution.java b/api/maven-api-core/src/main/java/org/apache/maven/api/MojoExecution.java
index 2aa5d8a2eb..15ffac662f 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/MojoExecution.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/MojoExecution.java
@@ -31,6 +31,8 @@ import org.apache.maven.api.xml.XmlNode;
  * An instance of this object is bound to the {@link org.apache.maven.api.di.MojoExecutionScoped}
  * and available as {@code mojoExecution} within {@link org.apache.maven.api.plugin.annotations.Parameter}
  * expressions.
+ *
+ * @since 4.0.0
  */
 @Experimental
 public interface MojoExecution {
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 66f93d204a..df26c2b8e9 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
@@ -29,6 +29,8 @@ import org.apache.maven.api.plugin.descriptor.lifecycle.Lifecycle;
 
 /**
  * Represents a maven plugin runtime
+ *
+ * @since 4.0.0
  */
 @Experimental
 public interface Plugin {
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/RemoteRepository.java b/api/maven-api-core/src/main/java/org/apache/maven/api/RemoteRepository.java
index 98dadefd3f..f4a425df1b 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/RemoteRepository.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/RemoteRepository.java
@@ -24,6 +24,8 @@ import org.apache.maven.api.annotations.Nonnull;
 
 /**
  * A remote repository that can be used to download or upload artifacts.
+ *
+ * @since 4.0.0
  */
 @Experimental
 @Immutable
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/Service.java b/api/maven-api-core/src/main/java/org/apache/maven/api/Service.java
index 5f53c06d50..d39bdc6766 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/Service.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/Service.java
@@ -27,6 +27,7 @@ import org.apache.maven.api.annotations.ThreadSafe;
  * Services can be retrieved from the session using the
  * {@link Session#getService(Class)} method.
  *
+ * @since 4.0.0
  * @see Session#getService(Class)
  */
 @Experimental
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/Session.java b/api/maven-api-core/src/main/java/org/apache/maven/api/Session.java
index 0bc177f75a..3aaa1f1165 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/Session.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/Session.java
@@ -502,15 +502,63 @@ public interface Session {
     @Nonnull
     VersionConstraint parseVersionConstraint(@Nonnull String versionConstraint);
 
-    Type requireType(String id);
+    /**
+     * Obtain the {@link Type} from the specified {@code id}.
+     * <p>
+     * Shortcut for {@code getService(TypeRegistry.class).require(...)}.
+     *
+     * @see org.apache.maven.api.services.TypeRegistry#require(String)
+     */
+    @Nonnull
+    Type requireType(@Nonnull String id);
 
-    Language requireLanguage(String id);
+    /**
+     * Obtain the {@link Language} from the specified {@code id}.
+     * <p>
+     * Shortcut for {@code getService(LanguageRegistry.class).require(...)}.
+     *
+     * @see org.apache.maven.api.services.LanguageRegistry#require(String)
+     */
+    @Nonnull
+    Language requireLanguage(@Nonnull String id);
 
-    Packaging requirePackaging(String id);
+    /**
+     * Obtain the {@link Packaging} from the specified {@code id}.
+     * <p>
+     * Shortcut for {@code getService(PackagingRegistry.class).require(...)}.
+     *
+     * @see org.apache.maven.api.services.PackagingRegistry#require(String)
+     */
+    @Nonnull
+    Packaging requirePackaging(@Nonnull String id);
 
-    ProjectScope requireProjectScope(String id);
+    /**
+     * Obtain the {@link ProjectScope} from the specified {@code id}.
+     * <p>
+     * Shortcut for {@code getService(ProjectScopeRegistry.class).require(...)}.
+     *
+     * @see org.apache.maven.api.services.ProjectScopeRegistry#require(String)
+     */
+    @Nonnull
+    ProjectScope requireProjectScope(@Nonnull String id);
 
+    /**
+     * Obtain the {@link DependencyScope} from the specified {@code id}.
+     * <p>
+     * Shortcut for {@code DependencyScope.forId(...)}.
+     *
+     * @see org.apache.maven.api.DependencyScope#forId(String)
+     */
+    @Nonnull
     DependencyScope requireDependencyScope(@Nonnull String id);
 
-    PathScope requirePathScope(String id);
+    /**
+     * Obtain the {@link PathScope} from the specified {@code id}.
+     * <p>
+     * Shortcut for {@code getService(PathScopeRegistry.class).require(...)}.
+     *
+     * @see org.apache.maven.api.services.PathScopeRegistry#require(String)
+     */
+    @Nonnull
+    PathScope requirePathScope(@Nonnull String id);
 }
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 05046da6a2..1f0d61b2c4 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
@@ -30,6 +30,8 @@ import org.apache.maven.api.plugin.descriptor.lifecycle.Lifecycle;
  * annotation.  If a {@code META-INF/maven/lifecycle.xml} file is packaged
  * in the plugin, Maven will provide a default implementation that will parse
  * the file and return the contained lifecycle definitions.
+ *
+ * @since 4.0.0
  */
 @Experimental
 @Consumer
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 2e28129d04..8fb3a7b947 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
@@ -20,6 +20,7 @@ package org.apache.maven.api.plugin;
 
 import java.util.function.Supplier;
 
+import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Provider;
 
 /**
@@ -32,6 +33,7 @@ import org.apache.maven.api.annotations.Provider;
  *
  * @since 4.0.0
  */
+@Experimental
 @Provider
 public interface Log {
     /**
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 3a5673c583..5d391e513f 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
@@ -26,9 +26,10 @@ import org.apache.maven.api.annotations.Nonnull;
 
 public interface ExtensibleEnumRegistry<T extends ExtensibleEnum> extends Service {
     @Nonnull
-    Optional<T> lookup(String id);
+    Optional<T> lookup(@Nonnull String id);
 
-    default T require(String 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/ProjectScopeRegistry.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectScopeRegistry.java
index a3b4f24a5d..edeae15488 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectScopeRegistry.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectScopeRegistry.java
@@ -19,8 +19,12 @@
 package org.apache.maven.api.services;
 
 import org.apache.maven.api.ProjectScope;
+import org.apache.maven.api.annotations.Experimental;
 
 /**
  * Manager for {@link ProjectScope}.
+ *
+ * @since 4.0.0
  */
+@Experimental
 public interface ProjectScopeRegistry extends ExtensibleEnumRegistry<ProjectScope> {}
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilder.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilder.java
index bc216c9d78..681c96d99e 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilder.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilder.java
@@ -22,11 +22,15 @@ import java.nio.file.Path;
 
 import org.apache.maven.api.Service;
 import org.apache.maven.api.Session;
+import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
  * Builds the effective settings from a user settings file and/or a global settings file.
+ *
+ * @since 4.0.0
  */
+@Experimental
 public interface SettingsBuilder extends Service {
 
     /**
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 201501ea50..7286fba9c1 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
@@ -20,9 +20,15 @@ package org.apache.maven.api.services;
 
 import java.util.List;
 
+import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Nonnull;
 import org.apache.maven.api.settings.Settings;
 
+/**
+ *
+ * @since 4.0.0
+ */
+@Experimental
 public interface SettingsBuilderResult {
 
     /**
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/services/SuperPomProvider.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/SuperPomProvider.java
index 8b94ab8389..ec52981a6a 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/SuperPomProvider.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/SuperPomProvider.java
@@ -25,6 +25,8 @@ import org.apache.maven.api.model.Model;
 
 /**
  * Provides the super POM that all models implicitly inherit from.
+ *
+ * @since 4.0.0
  */
 @Experimental
 public interface SuperPomProvider extends Service {
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilder.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilder.java
index 8de4a647e3..ecd4a2b2d2 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilder.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilder.java
@@ -25,6 +25,8 @@ import org.apache.maven.api.annotations.Nonnull;
 
 /**
  * Builds the effective toolchains from a user toolchains file and/or a global toolchains file.
+ *
+ * @since 4.0.0
  */
 @Experimental
 public interface ToolchainsBuilder extends Service {
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 7999fe157b..abdb0dcc76 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
@@ -22,12 +22,18 @@ import java.nio.file.Path;
 import java.util.Optional;
 
 import org.apache.maven.api.Session;
+import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Nonnull;
 import org.apache.maven.api.annotations.NotThreadSafe;
 import org.apache.maven.api.annotations.Nullable;
 
 import static org.apache.maven.api.services.BaseRequest.nonNull;
 
+/**
+ *
+ * @since 4.0.0
+ */
+@Experimental
 public interface ToolchainsBuilderRequest {
     @Nonnull
     Session getSession();
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 30ac872af3..dbf9d91d3f 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
@@ -20,9 +20,15 @@ package org.apache.maven.api.services;
 
 import java.util.List;
 
+import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Nonnull;
 import org.apache.maven.api.toolchain.PersistedToolchains;
 
+/**
+ *
+ * @since 4.0.0
+ */
+@Experimental
 public interface ToolchainsBuilderResult {
     /**
      * Gets the assembled toolchains.
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 8a2e85aaa3..8f6fb70311 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
@@ -27,6 +27,8 @@ import org.apache.maven.api.annotations.Nonnull;
 
 /**
  * Parses and evaluates version ranges encountered in dependency declarations.
+ *
+ * @since 4.0.0
  */
 @Experimental
 @Consumer
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverRequest.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverRequest.java
index eb1fc1f74f..3f3ac62355 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverRequest.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverRequest.java
@@ -26,6 +26,10 @@ import org.apache.maven.api.annotations.NotThreadSafe;
 
 import static org.apache.maven.api.services.BaseRequest.nonNull;
 
+/**
+ *
+ * @since 4.0.0
+ */
 @Experimental
 public interface VersionRangeResolverRequest {
 
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverResult.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverResult.java
index c626a9d674..3d2f038f14 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverResult.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverResult.java
@@ -26,6 +26,10 @@ import org.apache.maven.api.Version;
 import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Nonnull;
 
+/**
+ *
+ * @since 4.0.0
+ */
 @Experimental
 public interface VersionRangeResolverResult {
 
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolver.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolver.java
index c909cf6e9d..0a27f97d7c 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolver.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolver.java
@@ -27,6 +27,8 @@ import org.apache.maven.api.annotations.Nonnull;
 
 /**
  * Resolves artifact meta/pseudo versions.
+ *
+ * @since 4.0.0
  */
 @Experimental
 @Consumer
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 896a05788f..9c50f3e0f3 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
@@ -26,6 +26,10 @@ import org.apache.maven.api.annotations.NotThreadSafe;
 
 import static org.apache.maven.api.services.BaseRequest.nonNull;
 
+/**
+ *
+ * @since 4.0.0
+ */
 @Experimental
 public interface VersionResolverRequest {
 
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 90da559ac5..2897183e8c 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
@@ -26,6 +26,10 @@ import org.apache.maven.api.Version;
 import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Nonnull;
 
+/**
+ *
+ * @since 4.0.0
+ */
 @Experimental
 public interface VersionResolverResult {
 
diff --git a/api/maven-api-meta/src/main/java/org/apache/maven/api/annotations/Consumer.java b/api/maven-api-meta/src/main/java/org/apache/maven/api/annotations/Consumer.java
index 813002373f..63e720c62e 100644
--- a/api/maven-api-meta/src/main/java/org/apache/maven/api/annotations/Consumer.java
+++ b/api/maven-api-meta/src/main/java/org/apache/maven/api/annotations/Consumer.java
@@ -31,7 +31,7 @@ import java.lang.annotation.Target;
  * A type can be marked {@link Consumer} or {@link Provider} but not both. A type is assumed to be
  * {@link Consumer} if it is not marked either {@link Consumer} or {@link Provider}.
  * <p>
- * A package can be marked {@link Provider}. In this case, all types in the package are considered
+ * A package can be marked {@link Consumer}. In this case, all types in the package are considered
  * to be a provider type regardless of whether they are marked {@link Consumer} or {@link Provider}.
  *
  * @see Provider
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ExtensibleEnumProvider.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ExtensibleEnumProvider.java
index b81554bc86..7efa416d20 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ExtensibleEnumProvider.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ExtensibleEnumProvider.java
@@ -21,8 +21,24 @@ package org.apache.maven.api.spi;
 import java.util.Collection;
 
 import org.apache.maven.api.ExtensibleEnum;
+import org.apache.maven.api.annotations.Consumer;
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
 
+/**
+ * An SPI interface to extend Maven with a new enum value.
+ *
+ * @param <T> The type of extensible enum to extend
+ */
+@Experimental
+@Consumer
 public interface ExtensibleEnumProvider<T extends ExtensibleEnum> extends SpiService {
 
+    /**
+     * Registers new values for the T extensible enum.
+     *
+     * @return a collection of T instances to register
+     */
+    @Nonnull
     Collection<T> provides();
 }
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/LanguageProvider.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/LanguageProvider.java
index 9757d04f20..c6c06aec95 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/LanguageProvider.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/LanguageProvider.java
@@ -19,5 +19,12 @@
 package org.apache.maven.api.spi;
 
 import org.apache.maven.api.Language;
+import org.apache.maven.api.annotations.Consumer;
+import org.apache.maven.api.annotations.Experimental;
 
+/**
+ * @since 4.0.0
+ */
+@Experimental
+@Consumer
 public interface LanguageProvider extends ExtensibleEnumProvider<Language> {}
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParser.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParser.java
index 73e884fbc9..c9e2efc486 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParser.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParser.java
@@ -22,6 +22,7 @@ import java.nio.file.Path;
 import java.util.Map;
 import java.util.Optional;
 
+import org.apache.maven.api.annotations.Consumer;
 import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Nonnull;
 import org.apache.maven.api.annotations.Nullable;
@@ -31,8 +32,11 @@ import org.apache.maven.api.services.Source;
 /**
  * The {@code ModelParser} interface is used to locate and read {@link Model}s from the file system.
  * This allows plugging in additional syntaxes for the main model read by Maven when building a project.
+ *
+ * @since 4.0.0
  */
 @Experimental
+@Consumer
 public interface ModelParser extends SpiService {
 
     /**
@@ -64,6 +68,7 @@ public interface ModelParser extends SpiService {
      * @return an optional parsed {@link Model} or {@code null} if none could be found
      * @throws ModelParserException if the located model cannot be parsed
      */
+    @Nonnull
     default Optional<Model> locateAndParse(@Nonnull Path dir, @Nullable Map<String, ?> options)
             throws ModelParserException {
         return locate(dir).map(s -> parse(s, options));
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PathScopeProvider.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PathScopeProvider.java
index 2e2597b839..ab9b747a8a 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PathScopeProvider.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PathScopeProvider.java
@@ -19,5 +19,12 @@
 package org.apache.maven.api.spi;
 
 import org.apache.maven.api.PathScope;
+import org.apache.maven.api.annotations.Consumer;
+import org.apache.maven.api.annotations.Experimental;
 
+/**
+ * @since 4.0.0
+ */
+@Experimental
+@Consumer
 public interface PathScopeProvider extends ExtensibleEnumProvider<PathScope> {}
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ProjectScopeProvider.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ProjectScopeProvider.java
index c4a9a1f992..8a551af959 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ProjectScopeProvider.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ProjectScopeProvider.java
@@ -19,5 +19,12 @@
 package org.apache.maven.api.spi;
 
 import org.apache.maven.api.ProjectScope;
+import org.apache.maven.api.annotations.Consumer;
+import org.apache.maven.api.annotations.Experimental;
 
+/**
+ * @since 4.0.0
+ */
+@Experimental
+@Consumer
 public interface ProjectScopeProvider extends ExtensibleEnumProvider<ProjectScope> {}
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PropertyContributor.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PropertyContributor.java
index b29a0cc061..1bdfdeb5af 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PropertyContributor.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PropertyContributor.java
@@ -20,13 +20,17 @@ package org.apache.maven.api.spi;
 
 import java.util.Map;
 
+import org.apache.maven.api.annotations.Consumer;
 import org.apache.maven.api.annotations.Experimental;
 
 /**
  * Component able to contribute to Maven session user properties. This SPI component is invoked
  * very early, while there is no session created yet.
+ *
+ * @since 4.0.0
  */
 @Experimental
+@Consumer
 public interface PropertyContributor extends SpiService {
     /**
      * Invoked just before session is created with a mutable map that carries collected user properties so far.
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/TypeProvider.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/TypeProvider.java
index a47e99b586..3f60952d76 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/TypeProvider.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/TypeProvider.java
@@ -19,5 +19,12 @@
 package org.apache.maven.api.spi;
 
 import org.apache.maven.api.Type;
+import org.apache.maven.api.annotations.Consumer;
+import org.apache.maven.api.annotations.Experimental;
 
+/**
+ * @since 4.0.0
+ */
+@Experimental
+@Consumer
 public interface TypeProvider extends ExtensibleEnumProvider<Type> {}