Java Dokumentations-Kommentare: Javadoc

public class PersonOhneJavadoc {
    private String name = "--- ---";
    private int gebJahr = -9999;
    private int groesse = -99;
    
    public PersonOhneJavadoc(String name, int gebJahr) {
        setName(name);   // groesse wird bewusst nicht gesetzt - keine zwingend nötige Information
        if (gebJahr < 1900 || gebJahr > 2030) {   // direkt im Konstruktor, da 'gebJahr' unveränderbar (immutable)
            System.out.println("FEHLER - ungültiges GebJahr (1900 .. 2030): " + gebJahr   // hier OHNE 'this'
                    + " - auf " + this.gebJahr + " gesetzt");   // hier MIT 'this'!!
        } else {
            this.gebJahr = gebJahr;
        }
    }
    
    public void setName(String name) {
        String msgHead = "FEHLER - ungültiger Name: ";  // Abkürzungen: msg ... 'message', head ... hier 'Anfangs-Teil' 
        String msgTail = " -> Wert '" + this.name + "' bleibt bestehen."; // tail ... hier 'End-Teil'
        if (name == null) {
            System.out.println(msgHead + "null" + msgTail);
        } else if (!name.contains(" ")) {   // kein Leerzeichen
            System.out.println(msgHead + "enthält kein Leerzeichen" + msgTail);
        } else if (name.indexOf(" ") != name.lastIndexOf(" ")) {   // mehr als 1 Leerzeichen
            System.out.println(msgHead + "enthält mehr als 1 Leerzeichen" + msgTail);
        } else if (name.startsWith(" ") || name.endsWith(" ")) {   // Leerzeichen am Anfang oder Ende
            System.out.println(msgHead + "beginnt oder endet mit Leerzeichen" + msgTail);
        } else {
            this.name = name;
        }
    }

    public void setGroesse(int groesse) {
        if (groesse < 50 || groesse > 250) {
            System.out.println("FEHLER - ungültige Groesse (50 .. 250): " + groesse + "cm - bleibt auf " + this.groesse);
        }
        this.groesse = groesse;
    }

    public String getName() {
        return this.name;
    }

    public int getGebJahr() {
        return this.gebJahr;
    }
    
    public int getGroesse() {
        return this.groesse;
    }
    
    public String extractVorname() {
        int spacePos = name.indexOf(" ");  // kein Check auf -1 (nicht gefunden) nötig, da Prfg in Setter
        return name.substring(0, spacePos);
    }
    
    public String extractNachname() {
        int spacePos = name.indexOf(" ");  // kein Check auf -1 (nicht gefunden) nötig, da Prfg in Setter
        return name.substring(spacePos + 1);
    }

    public int calcAlter(int diesesJahr) {
        return (diesesJahr < 1900 || diesesJahr > 2030 || gebJahr == -9999) ? -99 : diesesJahr - gebJahr;
    }
}

/**
 * Einfache Personen-Klasse für Demonstrationszwecke vorwiegend zu Javadoc-Kommentaren. 
 * <p>Es sind nur Konstruktor (mit Parameter), Getter (mit Rückgabewert), Setter (mit Parameter) 
 * und 3 zusätzliche Methoden (eine mit Parameter UND Rückgabewert) vorhanden.</p>
 * <p>Sie dient auch als Beispiel INHALTLICH sinnvoller API-Dokumentation
 * (API = Application Programming Interface).</p>
 * <p>Eine solche API-Dokumentation soll die Nutzung der Klasse durch andere Programmierer 
 * <i>ohne Studium des Source-Codes</i> ermöglichen. Daher sind im besten Falle 
 * <i>alle</i> Infos zu:</p>
 * <ul>
 *   <li>genereller Zweck der Klasse oder Methode</li> 
 *   <li>Einheiten</li>
 *   <li>Gültigkeitsbereiche</li>
 *   <li>Sonderbedeutungen bestimmter übergebener und/oder zurückgegebener Werte (null, 0, negativ, ...)</li>
 *   <li>Fehlermöglichkeiten samt Reaktion der Methode(n)</li>
 *   <li>...</li>
 * </ul>
 * <p>anzugeben.</p>
 * <i><b>Wichtig:</b> (optionale) Zeilenschaltung nach erstem Satz (". &lt;br>"):
 *    Leerzeichen nach Punkt ZWINGEND, damit Satz-Ende erkannt wird!</i>
 *
 * @author renkin@spengergasse.at
 * @version 2020-12-06.v1
 */
public class PersonMitJavadoc {
    private String name = "--- ---";
    private int gebJahr = -9999;
    private int groesse = -99;

    /**
     * Konstruktor für Objekte der Klasse 'PersonMitJavadoc'.
     * <p>Name ist veränderbar, Geburtsjahr fix, als dritte Eigenschaft existiert die 
     *    (ebenfalls veränderbare) Größe, die zu Beginn auf 'nicht gesetzt' (= -99) steht.
     * </p>
     * 
     * @param  name  Details siehe Setter {@link #setName}
     * @param  gebJahr  das Geburtsjahr als 4-stellige Zahl (z.B. <i>1999</i>) zw. 1900 und 2030
     */
    public PersonMitJavadoc(String name, int gebJahr) {
        setName(name);   // groesse wird bewusst nicht gesetzt - keine zwingend nötige Information
        if (gebJahr < 1900 || gebJahr > 2030) {   // direkt im Konstruktor, da 'gebJahr' unveränderbar (immutable)
            System.out.println("FEHLER - ungültiges GebJahr (1900 .. 2030): " + gebJahr   // hier OHNE 'this'
                    + " - auf " + this.gebJahr + " gesetzt");   // hier MIT 'this'!!
        } else {
            this.gebJahr = gebJahr;
        }
    }

    /**
     * Setter für (vollen) Namen.
     * 
     * @param name VOLLER Name im Format "Vorname Nachname" (in dieser Reihenfolge, genau <b>ein</b> Leerzeichen). <br>
     * Wenn ein Teil unbekannt, auf '---' setzen. <br>
     * Muster für gültige Werte: nicht null, genau 1 Leerzeichen, dieses nicht am Anfang oder Ende.
     * Wenn übergebener Wert ungültig, <i>bleibt der alte Wert</i>
     */
    public void setName(String name) {
        String msgHead = "FEHLER - ungültiger Name: ";  // Abkürzungen: msg ... 'message', head ... hier 'Anfangs-Teil' 
        String msgTail = " -> Wert '" + this.name + "' bleibt bestehen."; // tail ... hier 'End-Teil'
        if (name == null) {
            System.out.println(msgHead + "null" + msgTail);
        } else if (!name.contains(" ")) {   // kein Leerzeichen
            System.out.println(msgHead + "enthält kein Leerzeichen" + msgTail);
        } else if (name.indexOf(" ") != name.lastIndexOf(" ")) {   // mehr als 1 Leerzeichen
            System.out.println(msgHead + "enthält mehr als 1 Leerzeichen" + msgTail);
        } else if (name.startsWith(" ") || name.endsWith(" ")) {   // Leerzeichen am Anfang oder Ende
            System.out.println(msgHead + "beginnt oder endet mit Leerzeichen" + msgTail);
        } else {
            this.name = name;
        }
    }

    /**
     * Setter für Körpergröße.
     * @param groesse in <b>cm</b> zwischen 50 und 250. Wenn übergebener Wert ungültig, <i>bleibt der alte Wert</i>
     */
    public void setGroesse(int groesse) {
        if (groesse < 50 || groesse > 250) {
            System.out.println("FEHLER - ungültige Groesse (50 .. 250): " + groesse + "cm - bleibt auf " + this.groesse);
        }
        this.groesse = groesse;
    }

    /**
     * Getter für Name.
     * @return der Name ('--- ---' vor erstem gültigen Setzen)
     */
    public String getName() {
        return this.name;
    }

    /**
     * Getter für Geburtsjahr.
     * @return das Geburtsjahr (-9999 vor erstem gültigen Setzen)
     */
    public int getGebJahr() {
        return this.gebJahr;
    }
    
    /**
     * Getter für Körpergröße.
     * @return Größe in cm (-99 vor erstem gültigen Setzen)
     */
    public int getGroesse() {
        return this.groesse;
    }
    
    /**
     * Extrahiert Namensteil <b>vor</b> dem Leerzeichen (EN: space). <br>
     * Keine Prüfung auf Vorhandensein des Leerzeichens nötig, da dies bereits im Setter geschieht.
     * 
     * @return liefert Vorname ("---" vor erstem gültigen Setzen)
     */
    public String extractVorname() {
        int spacePos = name.indexOf(" ");  // kein Check auf -1 (nicht gefunden) nötig, da Prfg in Setter
        return name.substring(0, spacePos);
    }
    
    /**
     * Extrahiert Namensteil <b>nach</b> dem Leerzeichen (EN: space).<br>
     * Keine Prüfung auf Vorhandensein des Leerzeichens nötig, da dies bereits im Setter geschieht.
     * 
     * @return liefert Nachname ("---" vor erstem gültigen Setzen)
     */
    public String extractNachname() {
        int spacePos = name.indexOf(" ");  // kein Check auf -1 (nicht gefunden) nötig, da Prfg in Setter
        return name.substring(spacePos + 1);
    }

    /**
     * Berechnet ungefähres Alter.
     * @param  diesesJahr  das Jahr, in dem das jeweilige Alter bestimmt werden soll. <br>
     *         Gültig zw. 1900 und 2030 (wie Gültigkeitsbereich von Geburtsjahr).
     * @return das ungefähre Alter in Jahren. Bei nicht gültigem 'diesesJahr' oder Geburtsjahr
     *         {@link #PersonMitJavadoc}: -99
     */
    public int calcAlter(int diesesJahr) {
        return (diesesJahr < 1900 || diesesJahr > 2030 || gebJahr == -9999) ? -99 : diesesJahr - gebJahr;
    }
}