refactor/Add documentation, made names more explicit and updated .gitlab-ci.yml

.gitlab-ci.yml

 image: maven:3.8.5-openjdk-17
 
 variables:
+  # This will suppress any download for dependencies and plugins or upload messages which would clutter the console log.
+  # `showDateTime` will show the passed time in milliseconds. You need to specify `--batch-mode` to make this work.
   MAVEN_OPTS: "-Dhttps.protocols=TLSv1.2 -Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository -Dorg.slf4j.simpleLogger.log.org.apache.maven.cli.transfer.Slf4jMavenTransferListener=WARN -Dorg.slf4j.simpleLogger.showDateTime=true -Djava.awt.headless=true"
+  MAVEN_CLI_OPTS: "--batch-mode --errors --fail-at-end --show-version -DinstallAtEnd=true -DdeployAtEnd=true"
   SPRING_PROFILES_ACTIVE: gitlab-ci 
 
 stages:
-  - test
-  - build
+  - compile_and_test
+  - generate_documentation
   - modify
-  - pages
+  - publish_pages
 
 cache:
   key: "${CI_JOB_NAME}" 
   paths:
     - .m2/repository 
 
-test:jdk17:
-  stage: test
+test_and_compile:
+  stage: compile_and_test
   script:
-    - mvn clean test
-  artifacts:
-    when: always
-    paths:
-      - target/site/jacoco
-    reports:
-      junit:
-        - target/surefire-reports/TEST-*.xml
-        - target/failsafe-reports/TEST-*.xml
+    - mvn clean test # Cleans the previous build and runs tests
   when: always
 
 generate_site_reports:
-  stage: build
+  stage: generate_documentation
   script:
-    - mvn site
+    - mvn site # Generates a website containing project documentation (including checkstyle report)
   artifacts:
     paths:
       - target/site/ 
 
-modify_html:
-  image: python:3.8-slim  # Using a Python image to run the script
+modify_html: # Modify the generated website containing project documentation to also link to JaCoCo coverage file 
+  image: python:3.8-slim  
   stage: modify
   script:
-    - pip install beautifulsoup4
-    - python scripts/update_html.py
+    - pip install beautifulsoup4 # Used to parse contents of HTML files 
+    - python scripts/add_jacoco_coverage_link_to_html.py # Script that modifies the HTML file to include a link to JaCoCo coverage file
   artifacts:
     paths:
       - target/site/
   dependencies:
     - generate_site_reports
 
-pages:
+# We move the code coverage reports generated by jacoco and mvn site to be served by Gitlab Pages (Settings -> Pages)
+publish_pages:
   image: alpine:latest
-  stage: pages
+  stage: publish_pages
   dependencies:
     - modify_html
   script:

pom.xml

@@ -152,15 +152,17 @@
 					</excludes>
 				</configuration>
 			</plugin>
+			<!-- Plugin that generates a site for the current project -->
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-site-plugin</artifactId>
     			<version>4.0.0-M13</version>
 			</plugin>	
+			<!-- Plugin allow execution of system and Java programs -->
 			<plugin>
 				<groupId>org.codehaus.mojo</groupId>
 				<artifactId>exec-maven-plugin</artifactId>
-				<version>3.0.0</version>
+				<version>3.2.0</version>
 				<executions>
 					<execution>
 					<id>update-html-report</id>
@@ -172,7 +174,7 @@
 						<executable>python</executable>
 						<workingDirectory>${project.basedir}/scripts</workingDirectory>
 						<arguments>
-						<argument>update_html.py</argument>
+						<argument>add_jacoco_coverage_link_to_html.py</argument>
 						</arguments>
 					</configuration>
 					</execution>
@@ -182,6 +184,7 @@
 	</build>
 	<reporting>
 		<plugins>
+			<!-- Generate Checkstyle Report -->
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-checkstyle-plugin</artifactId>

scripts/update_html.py → scripts/add_jacoco_coverage_link_to_html.py

-def modify_html(file_path):
+# Function is used to modify target/site/project-reports.html to include
+# a link to the JaCoCo generated coverage files at target/site/jacoco/index.html.
+def add_jacoco_coverage_link_to_html(file_path):
     import bs4
 
-    # Read the original HTML content from a file
+    # Open and read the HTML file at file_path
     with open(file_path, 'r', encoding='utf-8') as file:
         original_html = file.read()
 
-    # Parse the original HTML content using Beautiful Soup
+    # Parse the content of the HTML file using Beautiful Soup (bs4)
     soup = bs4.BeautifulSoup(original_html, features='html.parser')
     
     # Find the <ul> element that contains the Checkstyle link inside the Project Reports navigation section
+    # This is where we wanna add a list item for the JaCoCo coverage report
     nav_list = soup.find("li", class_="active").find("ul", class_="nav nav-list")
     
     # Create the new list item for JaCoCo
@@ -21,6 +24,7 @@ def modify_html(file_path):
     nav_list.append(new_li)
 
     # Find the table that contains the Checkstyle link
+    # This is where we wanna add a table that contains a link for the JaCoCo report
     table = soup.find("table", class_="table table-striped")
     
     # Create the new table row for JaCoCo
@@ -42,6 +46,5 @@ def modify_html(file_path):
     with open(file_path, 'w', encoding='utf-8') as file:
         file.write(str(soup.prettify()))
 
-# Specify the path to your HTML file
 file_path = 'target/site/project-reports.html'
-modify_html(file_path)
+add_jacoco_coverage_link_to_html(file_path)