updated comprehensive documentation

ci/scripts/utils/launch_java_agent.sh

@@ -5,21 +5,37 @@
 # ==============================================================================
 # Script Name: launch_java_agent.sh
 #
-# Description: This script automates the process of launching a Jenkins agent
-#              on a specified machine. It ensures that the necessary
-#              prerequisites are met, such as the availability of JAVA_HOME,
-#              the Jenkins agent launch directory, and proper authentication
-#              with GitHub.
+# Description:
+#        This script automates the process of launching a Jenkins agent
+#        on a specified machine. It ensures that the necessary
+#        prerequisites are met, such as the availability of JAVA_HOME,
+#        the Jenkins agent launch directory, and proper authentication
+#        with GitHub.
 #
-#              It then proceeds to check if the Jenkins node is online and
-#              decides whether to launch the Jenkins agent based on the node's
-#              status. The agent is launched in the background,
-#              and its PID is logged for reference.
+#       It then proceeds to check if the Jenkins node is online and
+#       decides whether to launch the Jenkins agent based on the node's
+#       status. The agent is launched in the background,
+#       and its PID is logged for reference.
 #
-# Prerequisites: JAVA_HOME must be set to a valid JDK installation.
-#                GitHub CLI (gh) must be installed and authenticated.
-#                Jenkins agent launch directory must exist and be specified.
-#                Jenkins controller URL and authentication token must be provided.
+# Prerequisites:
+#         JAVA_HOME must be set to a valid JDK installation.
+#         Jenkins agent launch directory must exist and be specified.
+#         GitHub CLI (gh) must be installed and authenticated for messeging
+#           from the Jenkins controller to GitHub PR via shell commands.
+#           Jenkins agent launch directory must exist and be specified.
+#           TODO: Must use GitHub CLI v2.2.5 (newer versoins have issues)
+#         Jenkins controller URL and authentication token must be provided.
+#         jenkins-secret-file:
+#           Must be present in the Jenkins agent launch directory.
+#           This file contains the secret key for the Jenkins agent
+#           established by the Jenkins administrator for each Node.
+#         jenkins_token:
+#           Must be present in the Jenkins agent launch directory.
+#           This file contains the user authentication token for the Jenkins controller
+#           to use the Remote API. This token can be generated by the user
+#           on the Jenkins controller.
+#         controller_user:
+#           Must be set to the Jenkins controller username corresponing to the jenkins_token.
 #
 # Usage: ./launch_java_agent.sh [now]
 #        The optional 'now' argument forces the script to launch the Jenkins
@@ -139,4 +155,4 @@ if [[ "${offline}" != "False" ]]; then
   fi
 else
   echo "Jenkins Agent is online (nothing done)"
-fi
+fi