diff --git a/generate_source_tarball.sh b/generate_source_tarball.sh
index 8eaca8f..4dc721f 100755
--- a/generate_source_tarball.sh
+++ b/generate_source_tarball.sh
@@ -15,42 +15,46 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-# Generates the 'source tarball' for JDK projects.
+# Generates the source tarball for OpenJDK projects.
+#
+# There are multiple ways to specify the source code location and version:
+#
+# 1. Specify the version (VERSION), the location of the Git repository
+#    (REPO_ROOT) and the root of the output tarball name (FILE_NAME_ROOT)
+# 2. Specify the version (VERSION) along with an upstream project name
+#    (PROJECT_NAME) and repository name (REPO_NAME) that can be used
+#    to construct the URL of the upstream OpenJDK repository.
+# 3. Specify OPENJDK_LATEST=1 and allow the script to obtain the JDK
+#    feature version from the spec file, which is then used to
+#    obtain the latest build promotion from the upstream repository.
+#
+# An appropriate bootstrap JDK is also required for when ./configure
+# is run within the checked out repository to generate the .src-rev.
+# file. This can be specified by setting BOOT_JDK.
 #
 # Example 1:
-# When used from local repo set REPO_ROOT pointing to file:// with your repo.
-# If your local repo follows upstream forests conventions, it may be enough to
-# set OPENJDK_URL.
+# This will check out the specified version from the specified
+# repository and construct a tarball called openjdk-17.0.3+5.tar.xz:
+#
+# $ VERSION=jdk-17.0.3+5 FILE_NAME_ROOT=open${VERSION} \
+#   REPO_ROOT=$HOME/projects/openjdk/upstream/17u \
+#   BOOT_JDK=/usr/lib/jvm/java-17-openjdk ./generate_source_tarball.sh
 #
 # Example 2:
+# This will check out the same version as example 1, but from the
+# upstream repository:
+#
+# $ VERSION=jdk-17.0.3+5 PROJECT_NAME=openjdk REPO_NAME=jdk17u \
+#   BOOT_JDK=/usr/lib/jvm/java-17-openjdk ./generate_source_tarball.sh
+#
+# Example 3:
 # This will read the OpenJDK feature version from the spec file, then create a
 # tarball from the most recent tag for that version in the upstream Git
 # repository.
 #
-# $ OPENJDK_LATEST=1 ./generate_source_tarball.sh
-# [...]
-# Tarball is: temp-generated-source-tarball-ujD/openjdk-17.0.10+6-ea.tar.xz
+# $ OPENJDK_LATEST=1 \
+#   BOOT_JDK=/usr/lib/jvm/java-17-openjdk ./generate_source_tarball.sh
 #
-# Unless you use OPENJDK_LATEST, you have to set PROJECT_NAME, REPO_NAME and
-# VERSION, e.g.:
-#
-# PROJECT_NAME=openjdk
-# REPO_NAME=jdk17u
-# VERSION=jdk-17.0.11+9
-#
-# or to e.g., prepare systemtap, icedtea7's jstack and other tapsets:
-#
-# VERSION=6327cf1cea9e
-# REPO_NAME=icedtea7-2.6
-# PROJECT_NAME=release
-# OPENJDK_URL=http://icedtea.classpath.org/hg/
-# TO_COMPRESS="*/tapset"
-#
-# They are used to create correct name and are used in construction of sources
-# URL (unless REPO_ROOT is set).
-#
-# This script creates a single source tarball out of the repository based on the
-# given tag and removes code not allowed in Fedora/RHEL.
 
 set -e
 
diff --git a/java-17-openjdk.spec b/java-17-openjdk.spec
index e747e26..063a90e 100644
--- a/java-17-openjdk.spec
+++ b/java-17-openjdk.spec
@@ -2486,6 +2486,9 @@ require "copy_jdk_configs.lua"
 %endif
 
 %changelog
+* Mon Jul  8 2024 Andrew Hughes <gnu.andrew@redhat.com> - 1:17.0.12.0.6-0.1.ea
+- generate_source_tarball.sh: Update examples in header for clarity
+
 * Mon Jul  8 2024 Thomas Fitzsimmons <fitzsim@redhat.com> - 1:17.0.12.0.6-0.1.ea
 - Update to jdk-17.0.12+6 (EA)
 - Add openjdk-17.0.12+6-ea.tar.xz to .gitignore