Merge pull request #36426 from nderwin-forks/feature/update-core-depl…

…oyment-javadocs

Update javadocs for various build items

core/deployment/src/main/java/io/quarkus/deployment/builditem/AdditionalApplicationArchiveMarkerBuildItem.java

@@ -4,7 +4,7 @@
 
 /**
  * A marker file that if present indicates that a given archive should be treated as an
- * application archive
+ * application archive.
  */
 public final class AdditionalApplicationArchiveMarkerBuildItem extends MultiBuildItem {
 

core/deployment/src/main/java/io/quarkus/deployment/builditem/AdditionalIndexedClassesBuildItem.java

@@ -6,8 +6,8 @@
 import io.quarkus.builder.item.MultiBuildItem;
 
 /**
- * Allows extensions to add classes to the index available via {@link CombinedIndexBuildItem}
- * The classes are loaded by the Deployment ClassLoader
+ * Allows extensions to add classes to the index available via {@link CombinedIndexBuildItem}.
+ * The classes are loaded by the Deployment ClassLoader.
  */
 public final class AdditionalIndexedClassesBuildItem extends MultiBuildItem {
 

core/deployment/src/main/java/io/quarkus/deployment/builditem/ApplicationArchivesBuildItem.java

@@ -24,7 +24,7 @@ public ApplicationArchivesBuildItem(ApplicationArchive root, Collection<Applicat
 
     /**
      * Returns an {@link ApplicationArchive} that represents the classes and resources that are part of the current
-     * project
+     * project.
      *
      * @return The root archive
      */
@@ -52,7 +52,7 @@ public Set<ApplicationArchive> getAllApplicationArchives() {
     }
 
     /**
-     * Returns the archive that contains the given class name, or null if the class cannot be found
+     * Returns the archive that contains the given class name, or null if the class cannot be found.
      *
      * @param className The class name
      * @return The application archive

core/deployment/src/main/java/io/quarkus/deployment/builditem/ApplicationIndexBuildItem.java

@@ -5,7 +5,7 @@
 import io.quarkus.builder.item.SimpleBuildItem;
 
 /**
- * The Jandex index of the application root
+ * The Jandex index of the application root.
  */
 public final class ApplicationIndexBuildItem extends SimpleBuildItem {
 

core/deployment/src/main/java/io/quarkus/deployment/builditem/ApplicationStartBuildItem.java

@@ -5,7 +5,7 @@
 /**
  * A symbolic class that is produced after the startup event has been fired.
  *
- * At this point it should be safe to open sockets and begin processing requests
+ * At this point it should be safe to open sockets and begin processing requests.
  */
 public final class ApplicationStartBuildItem extends SimpleBuildItem {
 

core/deployment/src/main/java/io/quarkus/deployment/builditem/ArchiveRootBuildItem.java

@@ -121,9 +121,8 @@ public Path getArchiveLocation() {
     }
 
     /**
-     *
      * Returns a path representing the archive root. Note that if this is a jar archive this is not the path to the
-     * jar, but rather a path to the root of the mounted {@link com.sun.nio.zipfs.ZipFileSystem}
+     * jar, but rather a path to the root of the mounted {@link com.sun.nio.zipfs.ZipFileSystem}.
      *
      * @return The archive root.
      * @deprecated in favor of {@link #getRootDirectories()}
@@ -134,27 +133,26 @@ public Path getArchiveRoot() {
     }
 
     /**
-     * Collection of path representing the archive's root directories. If there is a JAR among the paths
+     * Collection of paths representing the archive's root directories. If there is a JAR among the paths
      * (returned by {@link #getResolvedPaths()}) this method will return the path to the root of the mounted
      * {@link java.nio.file.ZipFileSystem}
      * instead.
      *
      * @deprecated in favor of {@link #getRootDirectories()}
-     *
-     * @return Collection of path representing the archive's root directories.
+     * @return Collection of paths representing the archive's root directories
      */
     @Deprecated
     public PathsCollection getRootDirs() {
         return PathsCollection.from(rootDirs);
     }
 
     /**
-     * Collection of path representing the archive's root directories. If there is a JAR among the paths
+     * Collection of paths representing the archive's root directories. If there is a JAR among the paths
      * (returned by {@link #getResolvedPaths()}) this method will return the path to the root of the mounted
      * {@link java.nio.file.ZipFileSystem}
      * instead.
      *
-     * @return Collection of path representing the archive's root directories.
+     * @return Collection of paths representing the archive's root directories
      */
     public PathCollection getRootDirectories() {
         return rootDirs;
@@ -164,8 +162,7 @@ public PathCollection getRootDirectories() {
      * Collection of paths that collectively constitute the application archive's content.
      *
      * @deprecated in favor of {@link #getResolvedPaths()}
-     *
-     * @return collection of paths that collectively constitute the application archive content.
+     * @return collection of paths that collectively constitute the application archive content
      */
     @Deprecated
     public PathsCollection getPaths() {
@@ -175,7 +172,7 @@ public PathsCollection getPaths() {
     /**
      * Collection of paths that collectively constitute the application archive's content.
      *
-     * @return collection of paths that collectively constitute the application archive content.
+     * @return collection of paths that collectively constitute the application archive content
      */
     public PathCollection getResolvedPaths() {
         return paths;

core/deployment/src/main/java/io/quarkus/deployment/builditem/BytecodeTransformerBuildItem.java

@@ -21,8 +21,8 @@ public final class BytecodeTransformerBuildItem extends MultiBuildItem {
     final BiFunction<String, ClassVisitor, ClassVisitor> visitorFunction;
 
     /**
-     * Function that can be applied to the inout bytes before it is passed into ASM. This should only be used
-     * in very specific circumstances. At the moment the only known valid use case is jacoco, which needs
+     * Function that can be applied to the input bytes before it is passed into ASM. This should only be used
+     * in very specific circumstances. At the moment the only known valid use case is JaCoCo, which needs
      * access to the unmodified class file bytes.
      */
     final BiFunction<String, byte[], byte[]> inputTransformer;
@@ -31,7 +31,7 @@ public final class BytecodeTransformerBuildItem extends MultiBuildItem {
      * A set of class names that need to be present in the const pool for the transformation to happen. These
      * need to be in JVM internal format.
      * <p>
-     * The transformation is only applied if at least one of the entries in the const pool is present
+     * The transformation is only applied if at least one of the entries in the const pool is present.
      * <p>
      * Note that this is an optimisation, and if another transformer is transforming the class anyway then
      * this transformer will always be applied.

core/deployment/src/main/java/io/quarkus/deployment/builditem/CapabilityBuildItem.java

@@ -59,7 +59,7 @@ public CapabilityBuildItem(String name) {
     /**
      * <b>IMPORTANT:</b> in most cases, capability build items should not be produced by build steps of specific
      * extensions but be configured in their extension descriptors instead. Capabilities produced from
-     * extension build steps aren't available for the Quarkus dev tools. As a consequences, such capabilities
+     * extension build steps aren't available for the Quarkus dev tools. As a consequence, such capabilities
      * can not be taken into account when analyzing extension compatibility during project creation or when
      * adding new extensions to a project.
      *

core/deployment/src/main/java/io/quarkus/deployment/builditem/CombinedIndexBuildItem.java

@@ -14,7 +14,7 @@
  * Compared to {@code BeanArchiveIndexBuildItem}, this index doesn't contain all CDI-related information.
  * On the other hand, it can contain classes from archives/dependencies that had no CDI component declared within them.
  *
- * The computing index can also be used to index classes on demand. This when {@link IndexView#getClassByName(DotName)}
+ * The computing index can also be used to index classes on demand, when {@link IndexView#getClassByName(DotName)}
  * is called. Note that this is a mutable index as this will add additional information, so in general this Index
  * should only be used if you actually need it.
  *

core/deployment/src/main/java/io/quarkus/deployment/builditem/ConfigDescriptionBuildItem.java

@@ -7,7 +7,7 @@
 
 /**
  * A build item that is not part of the standard build, but is only used to generate
- * example config files and docs
+ * example config files and docs.
  */
 public final class ConfigDescriptionBuildItem extends MultiBuildItem implements Comparable<ConfigDescriptionBuildItem> {
     private final String propertyName;

core/deployment/src/main/java/io/quarkus/deployment/builditem/CuratedApplicationShutdownBuildItem.java

@@ -11,7 +11,7 @@
  * Build Item that can be used to queue shutdown tasks that are run when the {@link io.quarkus.bootstrap.app.CuratedApplication}
  * is closed.
  * <p>
- * For production applications, this will be at the end of the maven/gradle build. For dev mode applications, this will be
+ * For production applications, this will be at the end of the Maven/Gradle build. For dev mode applications, this will be
  * when dev mode shuts down. For tests, it will generally be at the end of the test run. However, for continuous testing this
  * will be when the outer dev mode process shuts down. For unit style tests, this will usually be the end of the test.
  */
@@ -30,11 +30,11 @@ public CuratedApplicationShutdownBuildItem(QuarkusClassLoader baseCl, boolean fi
     }
 
     /**
-     * Adds a task to run when the application is closed
+     * Adds a task to run when the application is closed.
      *
      * @param task The task
      * @param firstRunOnly If this should only be added for the first augment step. This makes it possible to prevent tasks
-     *        being added for every build
+     *        being added for every build.
      */
     public synchronized void addCloseTask(Runnable task, boolean firstRunOnly) {
         if (firstRunOnly || firstRun) {

core/deployment/src/main/java/io/quarkus/deployment/builditem/DevServicesConfigResultBuildItem.java

@@ -3,7 +3,7 @@
 import io.quarkus.builder.item.MultiBuildItem;
 
 /**
- * Configuration property that is the result of start dev services.
+ * Configuration property that is the result of starting dev services.
  *
  * Used to start and configure dev services, any processor starting dev services should produce these items.
  *

core/deployment/src/main/java/io/quarkus/deployment/builditem/DevServicesLauncherConfigResultBuildItem.java

@@ -5,7 +5,7 @@
 import io.quarkus.builder.item.SimpleBuildItem;
 
 /**
- * Build item that contains the final results of all
+ * Build item that contains the final results of all configuration.
  */
 public final class DevServicesLauncherConfigResultBuildItem extends SimpleBuildItem {
 

core/deployment/src/main/java/io/quarkus/deployment/builditem/DevServicesResultBuildItem.java

@@ -9,13 +9,13 @@
 import io.quarkus.builder.item.MultiBuildItem;
 
 /**
- * BuildItem for running dev services
+ * BuildItem for running dev services.
  * Combines injected configs to the application with container id (if it exists).
  *
  * Processors are expected to return this build item not only when the dev service first starts,
  * but also if a running dev service already exists.
  *
- * {@link RunningDevService} helps to manage the lifecycle of the running dev service
+ * {@link RunningDevService} helps to manage the lifecycle of the running dev service.
  */
 public final class DevServicesResultBuildItem extends MultiBuildItem {
 

core/deployment/src/main/java/io/quarkus/deployment/builditem/DevServicesSharedNetworkBuildItem.java

@@ -11,16 +11,16 @@
 import io.quarkus.builder.item.MultiBuildItem;
 
 /**
- * A marker build item that, if any instances are provided during the build, the containers started by DevServices
+ * A marker build item that indicates, if any instances are provided during the build, the containers started by DevServices
  * will use a shared network.
  * This is mainly useful in integration tests where the application container needs to be able
- * to communicate with the services containers
+ * to communicate with the service containers.
  */
 public final class DevServicesSharedNetworkBuildItem extends MultiBuildItem {
 
     /**
      * Generates a {@code List<Consumer<BuildChainBuilder>> build chain builder} which creates a build step
-     * producing the {@link DevServicesSharedNetworkBuildItem} build item
+     * producing the {@link DevServicesSharedNetworkBuildItem} build item.
      */
     public static final class Factory implements Function<Map<String, Object>, List<Consumer<BuildChainBuilder>>> {
 

core/deployment/src/main/java/io/quarkus/deployment/builditem/ExecutorBuildItem.java

@@ -5,7 +5,7 @@
 import io.quarkus.builder.item.SimpleBuildItem;
 
 /**
- * The main executor for blocking tasks
+ * The main executor for blocking tasks.
  */
 public final class ExecutorBuildItem extends SimpleBuildItem {
 

core/deployment/src/main/java/io/quarkus/deployment/builditem/FeatureBuildItem.java

@@ -6,7 +6,7 @@
 import io.quarkus.deployment.Feature;
 
 /**
- * Represents a functionality provided by an extension. The name of the feature gets displayed in the log during application
+ * Represents functionality provided by an extension. The name of the feature gets displayed in the log during application
  * bootstrap.
  * <p>
  * An extension should provide at most one feature. The name must be unique. If multiple extensions register a feature of the

core/deployment/src/main/java/io/quarkus/deployment/builditem/GeneratedFileSystemResourceBuildItem.java

@@ -6,7 +6,7 @@
  * Used when resources generated by the build should not end up in the produced runnable artifact,
  * but in the file system inside the output directory of OutputTargetBuildItem.
  *
- * This is written to the file system for normal and dev mode, but not for test mode
+ * This is written to the file system for normal and dev mode, but not for test mode.
  */
 public final class GeneratedFileSystemResourceBuildItem extends MultiBuildItem {
     final String name;

core/deployment/src/main/java/io/quarkus/deployment/builditem/GeneratedFileSystemResourceHandledBuildItem.java

@@ -3,7 +3,7 @@
 import io.quarkus.builder.item.SimpleBuildItem;
 
 /**
- * Marker used only to ensure that the file system resources where properly written in dev-mode
+ * Marker used only to ensure that the file system resources where properly written in dev mode.
  */
 public final class GeneratedFileSystemResourceHandledBuildItem extends SimpleBuildItem {
 

core/deployment/src/main/java/io/quarkus/deployment/builditem/GeneratedNativeImageClassBuildItem.java

@@ -3,7 +3,7 @@
 import io.quarkus.builder.item.MultiBuildItem;
 
 /**
- * A generated class that is only applicable to native images
+ * A generated class that is only applicable to native images.
  */
 public final class GeneratedNativeImageClassBuildItem extends MultiBuildItem {
     final String name;

core/deployment/src/main/java/io/quarkus/deployment/builditem/IOThreadDetectorBuildItem.java

@@ -4,7 +4,7 @@
 import io.quarkus.runtime.IOThreadDetector;
 
 /**
- * A build items provides the ability to detect if the current thread is an IO thread
+ * A build item that provides the ability to detect if the current thread is an IO thread
  */
 public final class IOThreadDetectorBuildItem extends MultiBuildItem {
 

core/deployment/src/main/java/io/quarkus/deployment/builditem/InitTaskBuildItem.java

@@ -9,11 +9,11 @@
 
 /**
  * Represents an initialization task for the application.
- * Often extension perform some sort of initialization as part of the application startup.
+ * Often extensions perform some sort of initialization as part of the application startup.
  * There are cases where we want to externalize the initialization (e.g. in a pipeline).
  *
  * Often the task is run using the same artifact as the application but using a different command or
- * arguments. In the later case it might be deseriable to pass additional environment variable to both the
+ * arguments. In the later case it might be desirable to pass additional environment variables to both the
  * init tasks (to enable init) and the application (to disable the init).
  */
 public final class InitTaskBuildItem extends MultiBuildItem {
@@ -102,9 +102,9 @@ public InitTaskBuildItem withAppEnvVars(Map<String, String> appEnvVars) {
     /**
      * Flag for tasks that require access to the environment variables of the application.
      * Often tasks need to access resources, configured via environment variables. This
-     * flag expresses that the task should be executed using the same envrironment variables as the application.
+     * flag expresses that the task should be executed using the same environment variables as the application.
      *
-     * @return true when the task is meant to share environment variables with the application.
+     * @return true when the task is meant to share environment variables with the application
      */
     public boolean isSharedEnvironment() {
         return sharedEnvironment;
@@ -116,13 +116,13 @@ public InitTaskBuildItem withSharedEnvironment(boolean sharedEnvironment) {
     }
 
     /**
-     * Flag for tasks that need to share filesystem with the application.
-     * Often tasks need to access resources, configured via filesystem (e.g. local config files, kubernetes service binding
+     * Flag for tasks that need to share the file system with the application.
+     * Often tasks need to access resources, configured via the file system (e.g. local config files, Kubernetes service binding
      * etc).
      * In other cases, tasks may need to produce files needed by the application.
-     * This flag expresses that the task should share filesystem with the application.
+     * This flag expresses that the task should share the file system with the application.
      *
-     * @return true when the task is meant to share filesystem.
+     * @return true when the task is meant to share the file system
      */
     public boolean isSharedFilesystem() {
         return sharedFilesystem;

core/deployment/src/main/java/io/quarkus/deployment/builditem/InitTaskCompletedBuildItem.java

@@ -3,9 +3,9 @@
 import io.quarkus.builder.item.MultiBuildItem;
 
 /**
- * A symbolic class that represents that an initialization task has been complete.
+ * A symbolic class that represents that an initialization task has been completed.
  * Similar to {@link ServiceStartBuildItem} but focused on initialization tasks (e.g. db migrations etc) that are run during
- * runtime just before the application startups.
+ * runtime just before the application starts.
  * <p>
  * The build item is used, so that we can track when all initialization tasks have been completed.
  */

core/deployment/src/main/java/io/quarkus/deployment/builditem/LaunchModeBuildItem.java

@@ -7,7 +7,7 @@
 import io.quarkus.runtime.LaunchMode;
 
 /**
- * indicates the type of launch
+ * Indicates the type of launch.
  */
 public final class LaunchModeBuildItem extends SimpleBuildItem {
 
@@ -64,7 +64,6 @@ public boolean isAuxiliaryApplication() {
 
     /**
      * The dev mode type of the main application.
-     *
      */
     public Optional<DevModeType> getAuxiliaryDevModeType() {
         return auxiliaryDevModeType;