From c0c7d39b59e646a51bf3a6729065cceda9b0a0ad Mon Sep 17 00:00:00 2001
From: Alexey Semenyuk <asemenyuk@openjdk.org>
Date: Tue, 5 Aug 2025 01:42:45 +0000
Subject: [PATCH] 8364587: Update jpackage internal javadoc

Reviewed-by: almatvee
---
 .../jpackage/internal/PackagingPipeline.java  | 30 +++++++++++++++++++
 .../jpackage/internal/model/Application.java  |  4 +--
 .../internal/model/DefaultLauncherIcon.java   |  2 +-
 .../jdk/jpackage/internal/model/Launcher.java |  4 +--
 4 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/src/jdk.jpackage/share/classes/jdk/jpackage/internal/PackagingPipeline.java b/src/jdk.jpackage/share/classes/jdk/jpackage/internal/PackagingPipeline.java
index 10590a7aa8b..276bed4f31c 100644
--- a/src/jdk.jpackage/share/classes/jdk/jpackage/internal/PackagingPipeline.java
+++ b/src/jdk.jpackage/share/classes/jdk/jpackage/internal/PackagingPipeline.java
@@ -55,19 +55,49 @@ import jdk.jpackage.internal.util.function.ExceptionBox;
 
 final class PackagingPipeline {
 
+    /**
+     * Runs the pipeline for the given application.
+     *
+     * @param env the build environment
+     * @param app the application
+     */
     void execute(BuildEnv env, Application app) throws PackagerException {
         execute(appContextMapper.apply(createTaskContext(env, app)));
     }
 
+    /**
+     * Runs the pipeline for the given package.
+     * <p>
+     * Building a package may require a directory where the app image bits will be
+     * accumulated or the existing app image may be used. The decision is made based
+     * on the properties of the given package. A new build environment will be
+     * created if an intermediate directory is required. To access the build
+     * environment that will be used by the pipeline before running the pipeline
+     * create {@link StartupParameters} instance using
+     * {@link Builder#createStartupParameters(BuildEnv, Package, Path)} method.
+     *
+     * @param env       the build environment
+     * @param pkg       the package
+     * @param outputDir the output directory for the package file
+     */
     void execute(BuildEnv env, Package pkg, Path outputDir) throws PackagerException {
         execute((StartupParameters)createPackagingTaskContext(env, pkg, outputDir,
                 taskConfig, appImageLayoutForPackaging.apply(pkg)));
     }
 
+    /**
+     * Runs the pipeline using the startup parameters created with
+     * {@link Builder#createStartupParameters(BuildEnv, Package, Path)} call.
+     *
+     * @param startupParameters the pipeline startup parameters
+     */
     void execute(StartupParameters startupParameters) throws PackagerException {
         execute(pkgContextMapper.apply(createTaskContext((PackagingTaskContext)startupParameters)));
     }
 
+    /**
+     * The way to access packaging build environment before building a package in a pipeline.
+     */
     interface StartupParameters {
         BuildEnv packagingEnv();
     }
diff --git a/src/jdk.jpackage/share/classes/jdk/jpackage/internal/model/Application.java b/src/jdk.jpackage/share/classes/jdk/jpackage/internal/model/Application.java
index f164daf3eb0..943a42712c8 100644
--- a/src/jdk.jpackage/share/classes/jdk/jpackage/internal/model/Application.java
+++ b/src/jdk.jpackage/share/classes/jdk/jpackage/internal/model/Application.java
@@ -222,10 +222,10 @@ public interface Application extends BundleSpec {
 
     /**
      * Gets the additional properties of this application for the application entry
-     * in the app image (".jpackage") file.
+     * in the app image (".jpackage.xml") file.
      *
      * @return the additional properties of this application for the application
-     *         entry in ".jpackage" file
+     *         entry in ".jpackage.xml" file
      */
     Map<String, String> extraAppImageFileData();
 
diff --git a/src/jdk.jpackage/share/classes/jdk/jpackage/internal/model/DefaultLauncherIcon.java b/src/jdk.jpackage/share/classes/jdk/jpackage/internal/model/DefaultLauncherIcon.java
index 6e36949190e..4275b84ba80 100644
--- a/src/jdk.jpackage/share/classes/jdk/jpackage/internal/model/DefaultLauncherIcon.java
+++ b/src/jdk.jpackage/share/classes/jdk/jpackage/internal/model/DefaultLauncherIcon.java
@@ -29,7 +29,7 @@ import java.util.Optional;
 /**
  * Default application launcher icon.
  * <p>
- * Default icon is either loaded from the resources of {@link jdk.jpackage/} module or picked from the resource directory.
+ * Default icon is either loaded from the resources of {@link jdk.jpackage} module or picked from the resource directory.
  * <p>
  * Use {@link #INSTANCE} field to get an instance of this type.
  */
diff --git a/src/jdk.jpackage/share/classes/jdk/jpackage/internal/model/Launcher.java b/src/jdk.jpackage/share/classes/jdk/jpackage/internal/model/Launcher.java
index 9c20d5432ee..ac60b503fe4 100644
--- a/src/jdk.jpackage/share/classes/jdk/jpackage/internal/model/Launcher.java
+++ b/src/jdk.jpackage/share/classes/jdk/jpackage/internal/model/Launcher.java
@@ -173,10 +173,10 @@ public interface Launcher {
 
     /**
      * Gets the additional properties for application launcher entries in the app
-     * image (".jpackage") file.
+     * image (".jpackage.xml") file.
      *
      * @return the additional properties for application launcher entries in
-     *         ".jpackage" file
+     *         ".jpackage.xml" file
      */
     Map<String, String> extraAppImageFileData();