Merge pull request #14 from kneitzel/UpdateDocumentation

Update documentation

README.md

@@ -2,6 +2,8 @@
 
 Example Maven Project for a JavaFX Application.
 
+**Update**: Added reporting to create a site (html documentation of project)
+
 **Update**: Java 21 is now fully supported
 
 This projects includes multiple plugins:

documentation/de/PMD.md

@@ -0,0 +1,61 @@
+# PMD
+
+## Regeln für PMD konfigurieren
+In dem Projekt verwenden wir PMD, um die Code-Qualität sicherzustellen und 
+um allgemeine Fehler zu vermeiden. Die Regeln für die Codeanalyse sind in 
+der Datei pmd-ruleset.xml definiert, die im Hauptverzeichnis des Projekts 
+liegt.
+
+Diese Datei enthält spezifische Regelsätze, die an die Projektanforderungen 
+angepasst sind. Jeder Regelsatz innerhalb der pmd-ruleset.xml spezifiziert, 
+welche Probleme PMD im Code suchen und melden soll. Die Konfiguration umfasst
+verschiedene Kategorien wie Fehlerprävention, Code-Stil, Optimierung und 
+viele andere.
+
+Ein typischer Eintrag in dieser Datei sieht wie folgt aus:
+
+```xml
+<rule ref="category/java/bestpractices.xml/UnusedImports">
+    <priority>5</priority>
+</rule>
+```
+In diesem Beispiel wird die Regel UnusedImports aus dem Bereich der Best 
+Practices verwendet, um ungenutzte Importe im Code zu identifizieren. 
+Die Priorität dieser Regel ist auf 5 gesetzt, was einer niedrigen Priorität 
+entspricht.
+
+Um spezifische Bedürfnisse anzusprechen, können wir auch benutzerdefinierte 
+Regeln hinzufügen oder bestehende Regeln anpassen. Dies ermöglicht uns eine 
+flexible Anpassung der Codeanalyse, die dazu beiträgt, unseren Code sauber, 
+effizient und fehlerfrei zu halten.
+
+Für die effektive Nutzung von PMD ist es wichtig, dass alle Teammitglieder 
+verstehen, wie die pmd-ruleset.xml aufgebaut ist und wie sie zur Verbesserung
+der Codequalität beiträgt. Daher sollte jeder Entwickler mit dieser 
+Konfigurationsdatei vertraut sein und wissen, wie Änderungen daran vorgenommen
+werden.
+
+## Abbruch bei Regelverstößen
+
+In dem Maven-Projekt können wir durch das Festlegen spezifischer Ziele (Goals)
+des Maven PMD oder Checkstyle Plugins steuern, ob der Build-Prozess bei 
+Verstößen gegen festgelegte Regeln abgebrochen werden soll. Diese Funktion 
+ist besonders nützlich, um die Code-Qualität sicherzustellen und Fehler 
+frühzeitig im Entwicklungsprozess zu erkennen.
+
+Je nach Konfiguration des Projekts können diese Ziele bei PMD gewählt werden:
+- **pmd**: Bei Verstößen wird der weitere Build Prozess nicht abgebrochen
+- **check**: Strengere Überprüfung und der Build Prozess bricht bei Vertsößen ab.
+
+Damit dies direkt in den Properties konfiguriert werden kann, wird die
+Property pmd.target verwendet:
+```xml
+<pmd.target>pmd</pmd.target>
+```
+
+## Ergebnis der Analyse
+
+Das Ergebnis der Analyse findet sich nach der Überprüfung in target/pmd.xml.
+
+Um die Datei besser lesen zu können, sollte man sich die Datei einfach
+von der Entwicklungsumgebung formatieren lassen.

documentation/de/QuickStart.md

@@ -27,19 +27,31 @@ aufrufen.
 Um die Anwendung zu übersetzen kannst Du aufrufen:
 ```./mvnw package```
 
-### Bau des Images zur weitergabe
+### Bau des Images zur Weitergabe
 
 Um das Image zu bauen, rufst du einfach Maven mit dem Profil Image und dem
 Ziel install auf:
-```./mvnw -DImage install```
+```./mvnw -Dimage install```
 
 **Wichtig** Du kannst nicht das JavaFX Plugin mit dem Ziel javafx:jlink verwenden,
 da dieses Plugin zwingend eine Modulbeschreibung für das Projekt und alle
 Abhängigkeiten erfordert.
 
+### Komplette Übersetzung des Projekts incl. Dokumentation
+Mit dem folgenden Befehl lässt sich das ganze Projekt von grundauf neu übersetzen incl.
+der Erstellung der HTML Dokumentation des Projektes:
+```./mvnw -Dimage clean install site```
+
+- **-Dimage** aktiviert das Profil image, das für den Bau des Application Images zuständig ist
+- **clean** Mit dem Ziel clean wird am Anfang alles, was bereits ggf. schon an Übersetzungen vorhanden ist, entfernt wird.
+- **install** Durch install wird das ganze Projekt gebaut incl. Unit Tests, statischer Codeanalyse, ...
+- **site** Es wird die Dokumentation des Projektes gebaut.
+
 ## Ergebnisse der statischen Codeanalyse
 
 Die Codeanalyse läuft automatisch beim Bau des Projektes und die Ergebnisse
 finden sich in:
 - ./target/pmd.xml
 - ./target/spotbugsXml.xml
+
+Wenn die Site gebau wird, dann gibt es html Seiten mit den Ergebnissen von PMD und Spotbugs in der Site.

documentation/de/SpotBugs.md

@@ -0,0 +1,74 @@
+# SpotBugs
+
+## Verwendung der "null" Annotations
+
+In Java-Projekten ist es wichtig, potenzielle NullPointer-Exceptions zu
+vermeiden, die durch den unsachgemäßen Umgang mit Null-Werten entstehen
+können. Die Null Annotations von JetBrains bieten eine praktische Lösung,
+um solche Probleme frühzeitig im Code zu erkennen und entsprechende Warnungen
+über Tools wie Spotbugs zu erhalten.
+
+### Abhängigkeit
+Die notwendigen Annotations sind u.a. in der Library von JetBrains
+```xml
+<dependency>
+    <groupId>org.jetbrains</groupId>
+    <artifactId>annotations</artifactId>
+    <version>${jetbrains.annotations.version</version>
+    <scope>compile</scope>
+</dependency>
+```
+
+### Verwendung der Annotations im Code
+Nachdem die Bibliothek in deinem Projekt verfügbar ist, kannst du die 
+Annotations **@Nullable** und **@NotNull** verwenden, um anzugeben, ob eine
+Methode oder Variable Null-Werte akzeptieren darf oder nicht.
+
+#### @NotNull
+Die @NotNull Annotation wird verwendet, um anzugeben, dass ein Parameter,
+eine lokale Variable, ein Feld oder eine Methode niemals den Wert null
+annehmen sollte. Dies ist besonders wichtig in Methoden, die keine null
+Werte verarbeiten können, da es andernfalls zu einer NullPointerException
+führen könnte. Durch die Anwendung dieser Annotation kann deine
+Entwicklungsumgebung oder ein statischer Code-Analyse-Tool wie SpotBugs oder
+IntelliJ IDEA's integrierter Inspektor dich warnen, wenn es eine potenzielle
+Verletzung dieser Bedingung gibt.
+
+**Anwendungsbeispiele für @NotNull:**
+- Methodenparameter: Garantiert, dass übergebene Argumente nicht null sind.
+- Methodenrückgabetyp: Stellt sicher, dass die Methode keinen null Wert zurückgibt.
+- Felder: Verhindert, dass Klassenfelder auf null gesetzt werden.
+
+#### @Nullable
+Die @Nullable Annotation wird verwendet, um zu kennzeichnen, dass eine
+Variable, ein Parameter, ein Feld oder eine Methode null zurückgeben oder
+null akzeptieren kann. Diese Annotation ist nützlich, um klarzustellen, dass
+Methoden und Variablen sicher für den Umgang mit Nullwerten sind. Wenn eine
+Variable oder Methode als @Nullable gekennzeichnet ist, sollten Entwickler
+entsprechende Null-Checks durchführen, um NullPointerExceptions zu vermeiden.
+
+**Anwendungsbeispiele für @Nullable:**
+- Methodenparameter: Erlaubt explizit, dass übergebene Argumente null sein können.
+- Methodenrückgabetyp: Gibt an, dass die Methode möglicherweise null zurückgibt, und fordert den Aufrufer auf, dies zu überprüfen.
+- Felder: Erlaubt, dass Klassenfelder auf null gesetzt werden können.
+
+### Allgemeine Richtlinien
+**Konsistente Verwendung**: Es ist wichtig, diese Annotationen konsistent im
+gesamten Code zu verwenden, um ihre Effektivität zu maximieren. 
+Inkonsistenzen können zu Fehlinterpretationen und Fehlern führen.
+**Integration mit Tools**: Nutze Entwicklungswerkzeuge und statische 
+Code-Analyse-Tools, die diese Annotationen erkennen und respektieren 
+können, um die Sicherheit deines Codes zu erhöhen.
+**Dokumentation und Team-Kommunikation**: Stelle sicher, dass alle 
+Teammitglieder die Bedeutung und den korrekten Einsatz dieser Annotationen
+verstehen. Dies verbessert die Code-Qualität und verhindert Fehler in der
+Zusammenarbeit.
+
+Durch den durchdachten Einsatz von @NotNull und @Nullable kannst du die Robustheit deines Codes signifikant steigern und sicherstellen, dass deine Anwendungen weniger anfällig für Laufzeitfehler durch unerwartete Null-Werte sind.
+
+## Ergebnis der Analyse
+
+Das Ergebnis der Analyse findet sich nach der Überprüfung in target/spotbugsXml.xml.
+
+Um die Datei besser lesen zu können, sollte man sich die Datei einfach
+von der Entwicklungsumgebung formatieren lassen.

documentation/de/_Index.md

@@ -8,8 +8,9 @@
 - Überprüfung auf Aktualisierungen
 
 ## [Statische Codeanalyse](StaticCodeAnalysis.md)
-- PMD
+- [PMD](PMD.md)
-- SpotBugs
+- [SpotBugs](SpotBugs.md)
 
 ## Sonstiges
+- Reporting
 - Lombok

documentation/en/PMD.md

@@ -0,0 +1,61 @@
+# PMD
+
+## Rules for PMD
+
+In this project, we use PMD to ensure code quality and prevent common 
+mistakes. The rules for code analysis are defined in the pmd-ruleset.xml 
+file located in the main directory of the project.
+
+This file contains specific rule sets tailored to the project requirements. 
+Each rule set within the pmd-ruleset.xml specifies what issues PMD should 
+look for and report in the code. The configuration includes various 
+categories such as error prevention, code style, optimization, and many 
+others.
+
+A typical entry in this file looks like this:
+
+```xml
+<rule ref="category/java/bestpractices.xml/UnusedImports">
+    <priority>5</priority>
+</rule>
+```
+
+In this example, the UnusedImports rule from the best practices category is 
+used to identify unused imports in the code. The priority of this rule is set
+to 5, which indicates a low priority.
+
+To address specific needs, we can also add custom rules or modify existing
+ones. This allows us a flexible adjustment of the code analysis, which helps
+to keep our code clean, efficient, and error-free.
+
+For effective use of PMD, it is important that all team members understand
+how the pmd-ruleset.xml is structured and how it contributes to improving
+code quality. Therefore, every developer should be familiar with this
+configuration file and know how to make changes to it.
+
+## Stop build process on rule violations
+
+In the Maven project, we can control whether the build process should be
+aborted upon violations of specified rules by setting specific goals (Goals)
+of the Maven PMD or Checkstyle plugins. This function is particularly useful
+for ensuring code quality and detecting errors early in the development
+process.
+
+Depending on the project configuration, these goals can be selected for PMD:
+
+- **pmd**: Violations do not cause the build process to be aborted
+- **check**: Stricter verification and the build process is aborted upon
+violations.
+
+To enable configuration directly in the properties, the pmd.target property is used:
+
+```xml
+<pmd.target>pmd</pmd.target>
+```
+
+
+## Result of Analysis
+
+The result can be found inside target/pmd.xml.
+
+Formatting the file will make it much easier to read.

documentation/en/QuickStart.md

@@ -28,11 +28,20 @@ to build the application.
 ### Build the Image
 
 To build the image, the profile Image must be used:
-```./mvnw -DImage install```
+```./mvnw -Dimage install```
 
 **Important** You cannot build an image using the javafx plugin. The javafx plugin requires that you build a modular
 Java application and all dependencies providing a module description.
 
+### complete build including documentation
+To build the complete project from scratch and build all parts possible, you could use the following command:
+```./mvnw -Dimage clean install site```
+
+- **-Dimage** activates the profile image that is responsible to build the application image
+- **clean** cleans everything of previous builds.
+- **install** build the project (compile, build jar file, ...)
+- **site** creates the html documentation of the project
+
 ## Static code analysis results
 
 The static code analysis is done during the build of the application. The results can be found in

documentation/en/SpotBugs.md

@@ -0,0 +1,73 @@
+# SpotBugs
+
+## Using "null" Annotations
+In Java projects, it's important to avoid potential NullPointerExceptions 
+that can arise from improper handling of null values. JetBrains' Null
+Annotations offer a practical solution to detect such issues early in the
+code and receive corresponding warnings through tools like SpotBugs.
+
+### Dependency
+The necessary annotations are included in the JetBrains library:
+
+```xml
+<dependency>
+    <groupId>org.jetbrains</groupId>
+    <artifactId>annotations</artifactId>
+    <version>${jetbrains.annotations.version}</version>
+    <scope>compile</scope>
+</dependency>
+```
+
+### Using the Annotations in Code
+Once the library is available in your project, you can use the **@Nullable**
+and **@NotNull** annotations to indicate whether a method or variable can 
+accept null values.
+
+#### @NotNull
+The @NotNull annotation is used to specify that a parameter, local variable,
+field, or method should never accept a null value. This is especially
+important in methods that cannot process null values, as it could lead to a
+NullPointerException. By using this annotation, your development environment
+or a static code analysis tool like SpotBugs or IntelliJ IDEA's integrated
+inspector can warn you if there's a potential violation of this condition.
+
+**Examples of using @NotNull:**
+- Method parameters: Ensures that passed arguments are not null.
+- Method return types: Ensures that the method does not return a null value.
+- Fields: Prevents class fields from being set to null.
+
+#### @Nullable
+The @Nullable annotation is used to indicate that a variable, parameter,
+field, or method can return or accept null. This annotation is useful to
+clarify that methods and variables are safe for handling null values. If a
+variable or method is marked as @Nullable, developers should perform
+appropriate null checks to avoid NullPointerExceptions.
+
+**Examples of using @Nullable:**
+
+- Method parameters: Explicitly allows passed arguments to be null.
+- Method return types: Indicates that the method may return null, prompting the caller to check.
+- Fields: Allows class fields to be set to null.
+
+### General Guidelines
+**Consistent Use**: It's important to use these annotations consistently
+throughout the code to maximize their effectiveness. Inconsistencies can lead
+to misinterpretations and errors.
+
+**Integration with Tools**: Use development tools and static code analysis
+tools that can recognize and respect these annotations to enhance your code's
+safety.
+
+**Documentation and Team Communication**: Ensure that all team members
+understand the importance and correct use of these annotations. This improves
+code quality and prevents errors in collaboration.
+
+By thoughtfully using @NotNull and @Nullable, you can significantly enhance
+the robustness of your code and ensure that your applications are less
+susceptible to runtime errors caused by unexpected null values.
+
+## Result of Analysis
+
+The result can be found inside target/spotbugsXml.xml.
+
+Formatting the file will make it much easier to read.

documentation/en/_Index.md

@@ -8,8 +8,9 @@
 - Checking of Updates
 
 ## [Static Code Analysis](StaticCodeAnalysis.md)
-- PMD
+- [PMD](PMD.md)
-- FindBugs
+- [SpotBugs](SpotBugs.md)
 
 ## Other Topics
+- Reporting
 - Lombok

pom.xml

@@ -30,6 +30,9 @@
         <mockito.version>5.11.0</mockito.version>
 
         <!-- Plugin dependencies -->
+        <codehaus.version.plugin>2.16.2</codehaus.version.plugin>
+        <javafx.maven.plugin>0.0.8</javafx.maven.plugin>
+        <jpackage.maven.plugin>0.1.5</jpackage.maven.plugin>
 		<maven.clean.plugin>3.3.2</maven.clean.plugin>
         <maven.compiler.plugin>3.13.0</maven.compiler.plugin>
         <maven.dependency.plugin>3.6.1</maven.dependency.plugin>
@@ -37,14 +40,13 @@
 		<maven.enforcer.plugin>3.4.1</maven.enforcer.plugin>
 		<maven.install.plugin>3.1.2</maven.install.plugin>
 		<maven.jar.plugin>3.4.1</maven.jar.plugin>
+        <maven.javadoc.plugin>3.6.3</maven.javadoc.plugin>
+        <maven.project.info.reports.plugin>3.5.0</maven.project.info.reports.plugin>
 		<maven.resources.plugin>3.3.1</maven.resources.plugin>
-		<maven.site.plugin>4.0.0-M13</maven.site.plugin>
+		<maven.site.plugin>4.0.0-M14</maven.site.plugin>
         <maven.surfire.plugin>3.2.5</maven.surfire.plugin>
         <moditect.maven.plugin>1.0.0.RC2</moditect.maven.plugin>
-        <jpackage.maven.plugin>0.1.5</jpackage.maven.plugin>
+        <maven.pmd.plugin>3.22.0</maven.pmd.plugin>
-        <maven.pmd.version>3.22.0</maven.pmd.version>
-        <codehaus.version.plugin>2.16.2</codehaus.version.plugin>
-        <javafx.maven.plugin>0.0.8</javafx.maven.plugin>
         <spotbugs.maven.plugin>4.8.5.0</spotbugs.maven.plugin>
         <spotbugs.version>4.8.5</spotbugs.version>
 
@@ -237,7 +239,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-pmd-plugin</artifactId>
-                <version>${maven.pmd.version}</version>
+                <version>${maven.pmd.plugin}</version>
                 <configuration>
                     <minimumTokens>100</minimumTokens>
                     <targetJdk>${java.version}</targetJdk>
@@ -272,6 +274,20 @@
                 </executions>
             </plugin>
 
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>${maven.javadoc.plugin}</version>
+                <executions>
+                    <execution>
+                        <id>attach-javadocs</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+
             <!-- JavaFX Plugin to start application -->
             <plugin>
                 <groupId>org.openjfx</groupId>
@@ -284,17 +300,82 @@
         </plugins>
     </build>
 
+    <reporting>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-project-info-reports-plugin</artifactId>
+                <version>${maven.project.info.reports.plugin}</version>
+                <reportSets>
+                    <reportSet>
+                        <reports>
+                            <report>index</report>
+                            <report>dependencies</report>
+                            <report>licenses</report>
+                            <report>summary</report>
+                        </reports>
+                    </reportSet>
+                </reportSets>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>${maven.javadoc.plugin}</version>
+                <reportSets>
+                    <reportSet>
+                        <reports>
+                            <report>javadoc</report>
+                        </reports>
+                    </reportSet>
+                    <reportSet>
+                        <id>tests</id>
+                        <configuration>
+                            <show>private</show>
+                        </configuration>
+                        <reports>
+                            <report>test-javadoc</report>
+                        </reports>
+                    </reportSet>
+                </reportSets>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-pmd-plugin</artifactId>
+                <version>${maven.pmd.plugin}</version>
+                <reportSets>
+                    <reportSet>
+                        <reports>
+                            <report>pmd</report>
+                        </reports>
+                    </reportSet>
+                </reportSets>
+            </plugin>
+            <plugin>
+                <groupId>com.github.spotbugs</groupId>
+                <artifactId>spotbugs-maven-plugin</artifactId>
+                <version>${spotbugs.maven.plugin}</version>
+                <reportSets>
+                    <reportSet>
+                        <reports>
+                            <report>spotbugs</report>
+                        </reports>
+                    </reportSet>
+                </reportSets>
+            </plugin>
+        </plugins>
+    </reporting>
+
     <profiles>
 
         <!-- Profile that adds JLink and JPackage runs.
 
-             Add -PImage or -DImage to use this profile.
+             Add -Pimage or -Dimage to use this profile.
              -->
         <profile>
-            <id>Image</id>
+            <id>image</id>
             <activation>
                 <property>
-                    <name>Image</name>
+                    <name>image</name>
                 </property>
             </activation>
             <build>