diff --git a/generate_source_tarball.sh b/generate_source_tarball.sh
index 09a25fd..c89e74f 100755
--- a/generate_source_tarball.sh
+++ b/generate_source_tarball.sh
@@ -1,40 +1,44 @@
 #!/bin/bash
-# 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.3+5
-#
-# 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-21-openjdk.spec b/java-21-openjdk.spec
index 84a14c8..a4856e6 100644
--- a/java-21-openjdk.spec
+++ b/java-21-openjdk.spec
@@ -2549,6 +2549,7 @@ cjc.mainProgram(args)
 - Require tzdata 2023d due to local inclusion of JDK-8322725
 - Bump FreeType version to 2.13.2 following JDK-8316028
 - Install alt-java man page from the misc tarball as it is no longer in the JDK image
+- generate_source_tarball.sh: Update examples in header for clarity
 - Related: RHEL-52723
 
 * Tue Jul 30 2024 Andrew Hughes <gnu.andrew@redhat.com> - 1:21.0.2.0.13-3