From c5c046521b9152a58418a4d96cfcfd0aa4557680 Mon Sep 17 00:00:00 2001
From: "J. Neugebauer" <ngb@helmholtz-bi.de>
Date: Sun, 11 Dec 2022 13:34:21 +0100
Subject: [PATCH] Doku und Formatierungen

---
 src/main/java/schule/ngb/zm/Constants.java    |   5 +-
 src/main/java/schule/ngb/zm/Strokeable.java   |   2 +
 .../schule/ngb/zm/anim/AnimationGroup.java    |   1 -
 src/main/java/schule/ngb/zm/util/Faker.java   | 100 +++++++++++++++---
 .../schule/ngb/zm/util/io/FontLoader.java     |  31 ++++--
 .../schule/ngb/zm/util/io/ImageLoader.java    |   7 ++
 6 files changed, 115 insertions(+), 31 deletions(-)

diff --git a/src/main/java/schule/ngb/zm/Constants.java b/src/main/java/schule/ngb/zm/Constants.java
index feda9f3..ba37cd4 100644
--- a/src/main/java/schule/ngb/zm/Constants.java
+++ b/src/main/java/schule/ngb/zm/Constants.java
@@ -23,7 +23,7 @@ import java.util.function.DoubleUnaryOperator;
  * aktuell gehalten werden (beispielsweise {@link #runtime}).
  * <p>
  * Für die Implementierung eigener Klassen ist es oft hilfreich von
- * {@code Constants} zu erben, um die Methoden und Konstanten einfach im
+ * {@code Constants} zu erben, um die Methoden und Konstanten einfacher im
  * Programm nutzen zu können.
  * <pre><code>
  * class MyClass extends Constants {
@@ -1255,7 +1255,7 @@ public class Constants {
 	public static final double distance( double fromX, double fromY, double toX, double toY ) {
 		double diffX = toX - fromX;
 		double diffY = toY - fromY;
-		return sqrt(diffX*diffX + diffY*diffY);
+		return sqrt(diffX * diffX + diffY * diffY);
 	}
 
 	/**
@@ -1416,6 +1416,7 @@ public class Constants {
 	 * @param <T> Datentyp des Elements.
 	 * @return Ein zufälliges Element aus dem Array.
 	 */
+	@SafeVarargs
 	public static final <T> T choice( T... values ) {
 		return values[random(0, values.length - 1)];
 	}
diff --git a/src/main/java/schule/ngb/zm/Strokeable.java b/src/main/java/schule/ngb/zm/Strokeable.java
index 36b0e29..22b4921 100644
--- a/src/main/java/schule/ngb/zm/Strokeable.java
+++ b/src/main/java/schule/ngb/zm/Strokeable.java
@@ -201,6 +201,8 @@ public interface Strokeable extends Drawable {
 	 * Kontureigenschaften zu erstellen. Der aktuelle {@code Stroke} wird
 	 * zwischengespeichert.
 	 *
+	 * @param strokeType
+	 * @param strokeWeight
 	 * @return Ein {@code Stroke} mit den passenden Kontureigenschaften.
 	 */
 	static Stroke createStroke( Options.StrokeType strokeType, double strokeWeight ) {
diff --git a/src/main/java/schule/ngb/zm/anim/AnimationGroup.java b/src/main/java/schule/ngb/zm/anim/AnimationGroup.java
index 16b24ac..c1de074 100644
--- a/src/main/java/schule/ngb/zm/anim/AnimationGroup.java
+++ b/src/main/java/schule/ngb/zm/anim/AnimationGroup.java
@@ -9,7 +9,6 @@ public class AnimationGroup<T> extends Animation<T> {
 
 	List<Animation<T>> anims;
 
-
 	private boolean overrideEasing = false;
 
 	private int overrideRuntime = -1;
diff --git a/src/main/java/schule/ngb/zm/util/Faker.java b/src/main/java/schule/ngb/zm/util/Faker.java
index 6e9c62c..cb4d0d7 100644
--- a/src/main/java/schule/ngb/zm/util/Faker.java
+++ b/src/main/java/schule/ngb/zm/util/Faker.java
@@ -19,7 +19,7 @@ import java.time.LocalDateTime;
 import java.time.ZoneOffset;
 import java.util.ArrayList;
 import java.util.List;
-import java.util.function.Function;
+import java.util.function.*;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
@@ -28,10 +28,10 @@ import static java.lang.Math.log;
 import static schule.ngb.zm.Constants.random;
 
 /**
- * Hilfsklasse, um zufällige Beispieldaten zu erzeugen.
+ * Eine Helferklasse, um zufällige Beispieldaten zu erzeugen.
  * <p>
- * Die Klasse kann verschiedene Arten realistischer Beispieldaten erzeugen,
- * unter anderem Namen, E-Mail-Adressen, Passwörter oder Platzhalter-Bilder.
+ * Die Klasse kann verschiedene Arten realistischer Beispieldaten erzeugen.
+ * Unter anderem Namen, E-Mail-Adressen, Passwörter oder Platzhalter-Bilder.
  */
 @SuppressWarnings( "unused" )
 public final class Faker {
@@ -45,11 +45,6 @@ public final class Faker {
 	 */
 	public static final String FAKE_IMG_URL = "https://loremflickr.com/%d/%d";
 
-	public static void main( String[] args ) {
-		String text = Faker.fakeText(2000, 8);
-		System.out.println(text);
-	}
-
 	/**
 	 * Erzeugt ein Array mit den angegebenen Anzahl zufälliger Benutzerdaten.
 	 * <p>
@@ -83,8 +78,8 @@ public final class Faker {
 
 
 	/**
-	 * Erzeugt ein Array mit den angegebenen Anzahl zufälliger Namen (Vor- und
-	 * Nachname).
+	 * Erzeugt ein Array mit den angegebenen Anzahl zufälliger Namen im Format
+	 * "Vorname Nachname".
 	 *
 	 * @param count Anzahl der Beispieldaten.
 	 * @return Ein Array mit den Beispieldaten.
@@ -140,7 +135,7 @@ public final class Faker {
 
 	/**
 	 * Erzeugt ein Array mit den angegebenen Anzahl zufälliger
-	 * {@code Date}-Objekte.
+	 * {@code LocalDate}-Objekte, die ein Datum ohne Uhrzeit beschreiben.
 	 *
 	 * @param count Anzahl der Beispieldaten.
 	 * @return Ein Array mit den Beispieldaten.
@@ -158,6 +153,14 @@ public final class Faker {
 		return result;
 	}
 
+	/**
+	 * Erzeugt ein Array mit den angegebenen Anzahl zufälliger
+	 * {@code LocalDateTime}-Objekte, die einen Zeitpunkt mit Dateum und Uhrzeit
+	 * beschreiben,
+	 *
+	 * @param count Anzahl der Beispieldaten.
+	 * @return Ein Array mit den Beispieldaten.
+	 */
 	public static LocalDateTime[] fakeDatetimes( int count ) {
 		long nowEpoch = LocalDateTime.now().toEpochSecond(ZoneOffset.UTC);
 		long from = LocalDateTime.ofEpochSecond(nowEpoch - 18 * 365, 0, ZoneOffset.UTC).toEpochSecond(ZoneOffset.UTC);
@@ -171,6 +174,17 @@ public final class Faker {
 		return result;
 	}
 
+	/**
+	 * Erzeugt einen Blindtext mit der angegebenen Anzahl Worten, aufgeteilt in
+	 * die angegebene Anzahl Absätze.
+	 * <p>
+	 * Abssätze werden duch einen doppelten Zeilenumbruch {@code \n\n}
+	 * getrennt.
+	 *
+	 * @param words Anzahl Wörter im Text insgesamt.
+	 * @param paragraphs Anzahl Absätze.
+	 * @return Ein zufälliger Blindtext.
+	 */
 	public static String fakeText( int words, int paragraphs ) {
 		String basetext = "";
 		try(
@@ -204,6 +218,16 @@ public final class Faker {
 		return result;
 	}
 
+	/**
+	 * Erzeugt ein Array mit der angegebenen Anzahl zufällig erzeugter Integer
+	 * im angegebenen Bereich.
+	 *
+	 * @param count Anzahl der Zahlen im Array.
+	 * @param min Untere Grenze der Zufallszahlen.
+	 * @param max Obere Grenze der Zufallszahlen.
+	 * @return Ein Array mit Zufallszahlen.
+	 * @see Constants#random(int, int)
+	 */
 	public static int[] fakeIntArray( int count, int min, int max ) {
 		int[] arr = new int[count];
 		for( int i = 0; i < count; i++ ) {
@@ -212,14 +236,56 @@ public final class Faker {
 		return arr;
 	}
 
+	/**
+	 * Erzeugt eine Liste mit der angegebenen Anzahl zufällig erzeugter Integer
+	 * im angegebenen Bereich.
+	 * <p>
+	 * Ist {@code list} ein Listenobjekt, werden dei Zahlen an diese angehängt.
+	 * Wird {@code null} übergeben, wird eine neue {@link ArrayList} erzeugt.
+	 *
+	 * @param count Anzahl der erzeugten Zahlen.
+	 * @param min Untere Grenze der Zufallszahlen.
+	 * @param max Obere Grenze der Zufallszahlen.
+	 * @param list Eine Liste, die befüllt werden soll, oder {@code null}.
+	 * @return Ein Array mit Zufallszahlen.
+	 * @see Constants#random(int, int)
+	 */
 	public static List<Integer> fakeIntegerList( int count, int min, int max, List<Integer> list ) {
-		if( list == null ) {
-			list = new ArrayList<>(count);
-		}
+		List<Integer> result = (list == null) ? new ArrayList<>(count) : list;
+		fakeIntegers(count, min, max, result::add);
+		return result;
+	}
+
+	/**
+	 * Erzeugt die angegebene Anzahl Zufallszahlen im angegebenen Bereich und
+	 * übergibt sie an den angegebenen {@code Consumer}.
+	 *
+	 * Ein typischer Aufruf, um eine {@code #LinkedList} mit 100 Zufallszahlen
+	 * zu erzeugen könnte so aussehen:
+	 * <pre><code>
+	 * List&lt;Integer&gt; l = new LinkedList&lt;&gt;();
+	 * Faker.fakeIntegers(100, 0, 100, l::add);
+	 * </code></pre>
+	 *
+	 * @param count Anzahl der erzeugten Zahlen.
+	 * @param min Untere Grenze der Zufallszahlen.
+	 * @param max Obere Grenze der Zufallszahlen.
+	 * @param con {@code Consumer} für die Zahlen.
+	 */
+	public static void fakeIntegers( int count, int min, int max, Consumer<Integer> con ) {
 		for( int i = 0; i < count; i++ ) {
-			list.add(random(min, max));
+			con.accept(random(min, max));
 		}
-		return list;
+	}
+
+	public static <L> L fakeIntegers( int count, int min, int max, Supplier<L> sup, BiConsumer<L, Integer> con ) {
+		L result = sup.get();
+
+		for( int i = 0; i < count; i++ ) {
+			con.accept(result, random(min, max));
+		}
+
+		return result;
 	}
 
 	@SuppressWarnings( "unchecked" )
diff --git a/src/main/java/schule/ngb/zm/util/io/FontLoader.java b/src/main/java/schule/ngb/zm/util/io/FontLoader.java
index 122edc6..bb0b327 100644
--- a/src/main/java/schule/ngb/zm/util/io/FontLoader.java
+++ b/src/main/java/schule/ngb/zm/util/io/FontLoader.java
@@ -5,14 +5,21 @@ import schule.ngb.zm.util.Validator;
 
 import java.awt.Font;
 import java.awt.FontFormatException;
+import java.awt.Image;
 import java.io.File;
 import java.io.IOException;
 import java.io.InputStream;
-import java.net.MalformedURLException;
 import java.util.Map;
-import java.util.Objects;
 import java.util.concurrent.ConcurrentHashMap;
 
+/**
+ * Eine Helferklasse mit Klassenmethoden, um Schriftarten zu laden.
+ * <p>
+ * Schriftarten können von verschiedenen Quellen geladen werden. Schriftarten,
+ * die aus Dateien geladen wurden, werden in einem internen Cache gespeichert
+ * und nachfolgende Versuche, dieselbe Schriftart zu laden, werden aus dem Cache
+ * bedient.
+ */
 public class FontLoader {
 
 	private static final Map<String, Font> fontCache = new ConcurrentHashMap<>();
@@ -22,11 +29,12 @@ public class FontLoader {
 	 * <p>
 	 * Die Methode kann eine Liste von Schriften bekommen und probiert diese
 	 * nacheinander zu laden. Die erste Schrift, die Fehlerfrei geladen werden
-	 * kann, wird zurückgegeben. Kann keine der Schriften geladen werden, ist das
-	 * Ergebnis {@code null}.
+	 * kann, wird zurückgegeben. Kann keine der Schriften geladen werden, ist
+	 * das Ergebnis {@code null}.
 	 * <p>
-	 * Die gefundene Schrift wird unter ihrem Dateinamen in den Schriftenspeicher
-	 * geladen und kann danach in der Zeichenmaschine benutzt werden.
+	 * Die gefundene Schrift wird unter ihrem Dateinamen in den
+	 * Schriftenspeicher geladen und kann danach in der Zeichenmaschine benutzt
+	 * werden.
 	 * <p>
 	 * Eine Datei mit dem Namen "fonts/Font-Name.ttf" würde mit dem Namen
 	 * "Font-Name" geladen und kann danach zum Beispiel in einem
@@ -96,11 +104,12 @@ public class FontLoader {
 	 * <p>
 	 * Die Methode kann eine Liste von Schriften bekommen und probiert diese
 	 * nacheinander zu laden. Die erste Schrift, die Fehlerfrei geladen werden
-	 * kann, wird zurückgegeben. Kann keine der Schriften geladen werden, ist das
-	 * Ergebnis {@code null}.
+	 * kann, wird zurückgegeben. Kann keine der Schriften geladen werden, ist
+	 * das Ergebnis {@code null}.
 	 * <p>
-	 * Die gefundene Schrift wird unter ihrem Dateinamen in den Schriftenspeicher
-	 * geladen und kann danach in der Zeichenmaschine benutzt werden.
+	 * Die gefundene Schrift wird unter ihrem Dateinamen in den
+	 * Schriftenspeicher geladen und kann danach in der Zeichenmaschine benutzt
+	 * werden.
 	 * <p>
 	 * Eine Datei mit dem Namen "fonts/Font-Name.ttf" würde mit dem Namen
 	 * "Font-Name" geladen und kann danach zum Beispiel in einem
@@ -113,7 +122,7 @@ public class FontLoader {
 	 * @see #loadFont(String, String)
 	 */
 	public static Font loadFonts( String name, String... sources ) {
-		for( String fontSource: sources ) {
+		for( String fontSource : sources ) {
 			// TODO: Ignore exceptions in this case and throw own at end?
 			Font font = loadFont(name, fontSource);
 			if( font != null ) {
diff --git a/src/main/java/schule/ngb/zm/util/io/ImageLoader.java b/src/main/java/schule/ngb/zm/util/io/ImageLoader.java
index cd8e448..0d8ae45 100644
--- a/src/main/java/schule/ngb/zm/util/io/ImageLoader.java
+++ b/src/main/java/schule/ngb/zm/util/io/ImageLoader.java
@@ -18,6 +18,13 @@ import java.lang.ref.SoftReference;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 
+/**
+ * Eine Helferklasse mit Klassenmethoden, um Bilder zu laden.
+ * <p>
+ * Bilder können von verschiedenen Quellen als {@link Image} geladen werden. Die
+ * Objekte werden in einem internen Cache gespeichert und nachfolgende Versuche,
+ * dieselbe Quelle zu laden, werden aus dem Cache bedient.
+ */
 public final class ImageLoader {
 
 	public static boolean caching = true;