Missing annotations on api

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 {
 
     /**

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 {
 
     /**

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

@@ -31,6 +31,8 @@
  * 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 {

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

@@ -29,6 +29,8 @@
 
 /**
  * Represents a maven plugin runtime
+ *
+ * @since 4.0.0
  */
 @Experimental
 public interface Plugin {

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

@@ -24,6 +24,8 @@
 
 /**
  * A remote repository that can be used to download or upload artifacts.
+ *
+ * @since 4.0.0
  */
 @Experimental
 @Immutable

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

@@ -27,6 +27,7 @@
  * Services can be retrieved from the session using the
  * {@link Session#getService(Class)} method.
  *
+ * @since 4.0.0
  * @see Session#getService(Class)
  */
 @Experimental

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

@@ -502,15 +502,63 @@ Artifact createArtifact(
     @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);
 }

api/maven-api-core/src/main/java/org/apache/maven/api/plugin/LifecycleProvider.java

@@ -30,6 +30,8 @@
  * 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

api/maven-api-core/src/main/java/org/apache/maven/api/plugin/Log.java

@@ -20,6 +20,7 @@
 
 import java.util.function.Supplier;
 
+import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Provider;
 
 /**
@@ -32,6 +33,7 @@
  *
  * @since 4.0.0
  */
+@Experimental
 @Provider
 public interface Log {
     /**

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

@@ -26,9 +26,10 @@
 
 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 + "'"));
     }
 }

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> {}

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

@@ -22,11 +22,15 @@
 
 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 {
 
     /**

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

@@ -20,9 +20,15 @@
 
 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 {
 
     /**

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

@@ -25,6 +25,8 @@
 
 /**
  * Provides the super POM that all models implicitly inherit from.
+ *
+ * @since 4.0.0
  */
 @Experimental
 public interface SuperPomProvider extends Service {

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

@@ -25,6 +25,8 @@
 
 /**
  * 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 {

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

@@ -22,12 +22,18 @@
 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();

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

@@ -20,9 +20,15 @@
 
 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.

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

@@ -27,6 +27,8 @@
 
 /**
  * Parses and evaluates version ranges encountered in dependency declarations.
+ *
+ * @since 4.0.0
  */
 @Experimental
 @Consumer

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

@@ -26,6 +26,10 @@
 
 import static org.apache.maven.api.services.BaseRequest.nonNull;
 
+/**
+ *
+ * @since 4.0.0
+ */
 @Experimental
 public interface VersionRangeResolverRequest {
 

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

@@ -26,6 +26,10 @@
 import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Nonnull;
 
+/**
+ *
+ * @since 4.0.0
+ */
 @Experimental
 public interface VersionRangeResolverResult {
 

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

@@ -27,6 +27,8 @@
 
 /**
  * Resolves artifact meta/pseudo versions.
+ *
+ * @since 4.0.0
  */
 @Experimental
 @Consumer

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

@@ -26,6 +26,10 @@
 
 import static org.apache.maven.api.services.BaseRequest.nonNull;
 
+/**
+ *
+ * @since 4.0.0
+ */
 @Experimental
 public interface VersionResolverRequest {
 

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

@@ -26,6 +26,10 @@
 import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Nonnull;
 
+/**
+ *
+ * @since 4.0.0
+ */
 @Experimental
 public interface VersionResolverResult {
 

api/maven-api-meta/src/main/java/org/apache/maven/api/annotations/Consumer.java

@@ -31,7 +31,7 @@
  * 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

api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ExtensibleEnumProvider.java

@@ -21,8 +21,24 @@
 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();
 }

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> {}