Docs: Add JavaDoc

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/check/Checkable.java

@@ -93,7 +93,7 @@ public abstract class Checkable implements Serializable {
 
 	/**
 	 * This should be called before executing a check if low memory consumption
-	 * method has been enabled. This should create edges and additional meta
+	 * method has been enabled. Creates edges and additional meta
 	 * information necessary to perform checks.
 	 */
 	public void prepareForChecking() {
@@ -101,20 +101,19 @@ public abstract class Checkable implements Serializable {
 	}
 
 	/**
-	 * This should be called after checking has been done. This should remove any
-	 * created meta information like edges to free up additional memory space
+	 * This should be called after checking has been done. Removes any
+	 * created meta information like edges to free up memory.
 	 */
 	public void clearMetaInformation() {
 		this.accept(new ClearMetaInformationVisitor());
 	}
 
 	/**
-	 * This method checks if the object or any object contained within this
-	 * checkable has an error. It counts as an error if the result status if the
-	 * given check is <code>DEPENDENCIES_NOT_MET<code>.
+	 * Checks if the object, or any object in its datastructure, has a specific error or is not fulfilling the dependencies
+	 * of it.
 	 *
-	 * @param checkIdentifier the name of the check for which an error is searched
-	 * @return true if an error has been found with the given check
+	 * @param checkIdentifier the associated CheckID of this error
+	 * @return true if the error was found, false otherwise
 	 */
 	public boolean containsError(CheckId checkIdentifier) {
 		try {
@@ -125,6 +124,12 @@ public abstract class Checkable implements Serializable {
 		return false;
 	}
 
+	/**
+	 * Checks if this checkable has an error or is not meeting the dependencies for it.
+	 *
+	 * @param checkIdentifier the associated CheckID of this error
+	 * @return true if the error was found, false otherwise
+	 */
 	public boolean hasError(CheckId checkIdentifier) {
 		CheckResult cs = getCheckResult(checkIdentifier);
 		if (cs == null) {
@@ -156,7 +161,7 @@ public abstract class Checkable implements Serializable {
 
 	/**
 	 *
-	 * @return all check results for this checkable.
+	 * @return all check results of this checkable.
 	 */
 	public Map<CheckId, CheckResult> getAllCheckResults() {
 		return checkResults;
@@ -179,9 +184,7 @@ public abstract class Checkable implements Serializable {
 	}
 
 	/**
-	 * Checks whether this checkable has an error. Dependency errors are not
-	 * considered for this function. This will only check this checkable and not
-	 * traverse any checkables contained in this instance.
+	 * Checks whether this checkable has any error, barring dependency errors.
 	 * 
 	 * @return true if it has an error, otherwise false
 	 */
@@ -218,7 +221,7 @@ public abstract class Checkable implements Serializable {
 	}
 
 	/**
-	 * Clears all errors from this checkable
+	 * Clears the checkResults list of this checkable.
 	 */
 	public void clearCheckResults() {
 		setValidated(false);
@@ -226,16 +229,16 @@ public abstract class Checkable implements Serializable {
 	}
 
 	/**
-	 * Removes all errors from this instance and all contained checkables.
+	 * Clears the checkResults list of this checkable and all child objects in its datastructure.
 	 */
 	public final void clearAllContainedCheckResults() {
 		this.accept(new ClearCheckResultsVisitor());
 	}
 
 	/**
+	 * Checks if this checkable contains any error within its datastructure.
 	 *
-	 * @return false if the checkable or all checkables contained in this one don't
-	 *         have any error.
+	 * @return true if any checkable of this datastructure contains an error, false otherwise
 	 */
 	public final boolean containsAnyError() {
 		try {
@@ -246,6 +249,10 @@ public abstract class Checkable implements Serializable {
 		return false;
 	}
 
+	/**
+	 * Checks if this checkable has any error
+	 * @return true if this checkable has any error, false otherwise
+	 */
 	public boolean hasAnyError() {
 		for (CheckResult cr : checkResults.values()) {
 			if (cr.getResultStatus() == ResultStatus.ERROR

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/datastructure/CityObject.java

@@ -48,20 +48,24 @@ public abstract class CityObject extends GmlElement {
     private final List<GenericAttribute> genericAttributeList = new ArrayList<>();
 
     /**
-     * Recreates the CityGML4j geometry in this object. The CityGML4j geometry is
-     * deleted from the data structure as was mapped to the city doctor data
-     * structure. For writing CityGML files the geometry has to be restored. Also
-     * maps changes to geometry back to CityGML4j
-     *
-     * @param factory needed to create CityGML4j data structures
-     * @param config  contains information whether a city doctor point was
-     *                transformed to a different coordinate system. It would need to
-     *                be transformed to the original coordinate system
+     * Recreates the CityGML4j geometry in this object's datastructure using the CityDoctor geometries.
+     * The original CityGML4j geometry is deleted after parsing to reduce the memory overhead of {@link CityObject CityObjects}.
+     * <p/>
+     * Recreation of the geometries is needed for writing validation results to the QualityADE, as well as for the export
+     * of repaired geometries from CityDoctor's internal datastructure.
+     * @param factory the GeometryFactory used for creation of CityGml4j geometry objects
+     * @param config the configuration settings of the parser
      */
     public final void reCreateGeometries(GeometryFactory factory, ParserConfiguration config) {
         this.accept(new GmlGeometryRebuilder(factory, config));
     }
 
+    /**
+     * Rebuilds the CityGML4j geometries of this object.
+     *
+     * @param factory the GeometryFactory used for creation of CityGml4j geometry objects
+     * @param config  the configuration settings of the parser
+     */
     public abstract void rebuildGeometries(GeometryFactory factory, ParserConfiguration config);
 
     /**
@@ -72,36 +76,58 @@ public abstract class CityObject extends GmlElement {
     public abstract AbstractCityObject getGmlObject();
 
     /**
-     * Remove the CityGML4j geometries from this CityObject to save memory.
+     * Remove the CityGML4j geometries from this CityObject to reduce memory overhead.
      */
     public abstract void unsetGmlGeometries();
 
     /**
-     * Removes all CityGML4J geometries from this CityObject and all children in its datastructure.
+     * Removes all CityGML4J geometries from this CityObject and child objects of its datastructure to reduce
+     * the memory overhead.
      */
     public final void clearGmlGeometries() {
         this.accept(new UnsetGeometriesVisitor());
     }
 
+    /**
+     * Adds a Geometry to this object.
+     * @param geom the Geometry to add.
+     */
     public void addGeometry(Geometry geom) {
         Objects.requireNonNull(geom);
         geometryList.add(geom);
         geom.setParent(this);
     }
 
-
+    /**
+     * Returns all Geometries of this object.
+     * @return a list of the Geometries.
+     */
     public List<Geometry> getGeometries() {
         return geometryList;
     }
 
+    /**
+     * Removes a Geometry from this object.
+     * @param lod the {@link Lod} of the Geometry.
+     */
     public void removeGeometry(Lod lod) {
         geometryList.removeIf(geom -> geom.getLod() == lod);
     }
 
+    /**
+     * Removes a Geometry from this object.
+     * @param lod the {@link Lod} of the Geometry.
+     * @param type the {@link GeometryType} of the Geometry.
+     */
     public void removeGeometry(Lod lod, GeometryType type) {
         geometryList.removeIf(geom -> geom.getLod() == lod && geom.getType() == type);
     }
 
+    /**
+     * Returns the Geometry with the highest LOD of this object. If multiple Geometries share the highest LOD, the one
+     * that was added first will be returned.
+     * @return the Geometry with the highest LOD
+     */
     public Geometry getHighestLodGeometry() {
         Geometry highestLodGeometry = null;
         Lod highestLod = null;
@@ -115,29 +141,47 @@ public abstract class CityObject extends GmlElement {
     }
 
     /**
-     * Returns the top-level CityObject (like Building or Tunnel) belonging to this object.
+     * Returns the top-level CityObject (e.g. Building, Tunnel, Vegetation etc.) belonging to this object.
      */
     public abstract CityObject getTopLevelCityObject();
 
     /**
-     * Returns the display text for this object
+     * Returns a String representation of this object for display in the featuretab TreeViews in the format of
+     * "[FeatureType] Gml-ID"
+     * @return the String representation.
      */
     public String getDisplayText() {
         return String.format("[%s] %s", this.getClass().getSimpleName(), this.getGmlId().toString());
     }
 
+    /**
+     * Returns the color for rendering of this object's polygons.
+     * @return color for this object
+     */
     public Color getRenderColor() {
         return Color.WHITE;
     }
 
+    /**
+     * Adds a GenericAttribute to this object.
+     * @param genericAttribute the attribute to add.
+     */
     public void addGenericAttribute(GenericAttribute genericAttribute) {
         genericAttributeList.add(genericAttribute);
     }
 
+    /**
+     * Returns all GenericAttributes of this object.
+     * @return a list of the GenericAttributes.
+     */
     public List<GenericAttribute> getGenericAttributes() {
         return genericAttributeList;
     }
 
+    /**
+     * Returns the CityGML FeatureType of this object.
+     * @return this object's FeatureType.
+     */
     public abstract FeatureType getFeatureType();
 
     @Override

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/datastructure/Geometry.java

@@ -28,7 +28,6 @@ import de.hft.stuttgart.citydoctor2.utils.SerializablePair;
 
 import java.io.Serial;
 import java.util.*;
-import java.util.Map.Entry;
 
 /**
  * Representation of a geometry containing the polygons and edges

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/utils/CheckErrorFound.java

 package de.hft.stuttgart.citydoctor2.utils;
 
+/**
+ * This Throwable signals that a requested CheckError was found.
+ */
 public class CheckErrorFound extends Throwable {
 
 

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/utils/visitors/CheckableErrorCollector.java

@@ -6,10 +6,18 @@ import de.hft.stuttgart.citydoctor2.check.Checkable;
 
 import java.util.List;
 
+/**
+ * This Visitor collects all CheckErrors in the datastructure of a checkable.
+ */
 public class CheckableErrorCollector extends AbstractCheck {
 
     List<CheckError> errors;
 
+    /**
+     * Collects all CheckErrors into a list
+     *
+     * @param errors the list
+     */
     public CheckableErrorCollector(List<CheckError> errors) {
         this.errors = errors;
     }

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/utils/visitors/CityObjectCollector.java

@@ -7,12 +7,17 @@ import java.util.HashSet;
 import java.util.Set;
 
 /**
- * This AbstractCheck collects all CityObjects in the substructure of a Feature.
+ * This Visitor collects all sub-CityObjects that are in the datastructure of a CityObject (including itself) in a Set.
  */
 public class CityObjectCollector extends AbstractCheck {
 
     private final Set<CityObject> objects = new HashSet<>();
 
+    /**
+     * Returns the collected CityObjects.
+     *
+     * @return A set of CityObjects
+     */
     public Set<CityObject> getCityObjects() {
         return objects;
     }

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/utils/visitors/ClearCheckResultsVisitor.java

@@ -3,6 +3,9 @@ package de.hft.stuttgart.citydoctor2.utils.visitors;
 import de.hft.stuttgart.citydoctor2.check.AbstractCheck;
 import de.hft.stuttgart.citydoctor2.check.Checkable;
 
+/**
+ * This Visitor removes the check results from a CityObject and the objects in its datastructure.
+ */
 public class ClearCheckResultsVisitor extends AbstractCheck {
 
     @Override

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/utils/visitors/ClearMetaInformationVisitor.java

@@ -3,6 +3,9 @@ package de.hft.stuttgart.citydoctor2.utils.visitors;
 import de.hft.stuttgart.citydoctor2.check.AbstractCheck;
 import de.hft.stuttgart.citydoctor2.datastructure.Geometry;
 
+/**
+ * This Visitor removes the metadata created by the {@link PrepareForCheckingVisitor} for the low-memory consumption mode.
+ */
 public class ClearMetaInformationVisitor extends AbstractCheck {
 
     @Override

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/utils/visitors/ContainsAnyErrorVisitor.java

@@ -5,8 +5,22 @@ import de.hft.stuttgart.citydoctor2.check.Checkable;
 import de.hft.stuttgart.citydoctor2.utils.CheckErrorFound;
 import de.hft.stuttgart.citydoctor2.utils.ThrowUtils;
 
+/**
+ * This visitor checks if a checkable contains any error in its datastructure.
+ * <p><p/>
+ * This visitor's check method terminates early by throwing an unchecked {@link CheckErrorFound},
+ * use {@link #checkObject(Checkable) ContainsAnyErrorVisitor.checkObject(Checkable)} to handle the Throwable.
+ */
 public class ContainsAnyErrorVisitor extends AbstractCheck {
 
+    /**
+     * Checks if a Checkable, or any Object in its datastructure, contains any error.
+     * <p>
+     * Terminates early upon finding an error by throwing {@link CheckErrorFound}
+     *
+     * @param checkable The object to check
+     * @throws CheckErrorFound when any Error is found
+     */
     public static void checkObject(Checkable checkable) throws CheckErrorFound {
         checkable.accept(new ContainsAnyErrorVisitor());
     }

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/utils/visitors/ContainsErrorVisitor.java

@@ -6,10 +6,25 @@ import de.hft.stuttgart.citydoctor2.check.Checkable;
 import de.hft.stuttgart.citydoctor2.utils.CheckErrorFound;
 import de.hft.stuttgart.citydoctor2.utils.ThrowUtils;
 
+/**
+ * This visitor checks if a checkable contains a specific error in its datastructure.
+ * <p><p/>
+ * This visitor's check method terminates early by throwing an unchecked {@link CheckErrorFound},
+ * use {@link #checkObject(Checkable, CheckId) ContainsAnyErrorVisitor.checkObject(Checkable, CheckId)} to handle the Throwable.
+ */
 public class ContainsErrorVisitor extends AbstractCheck {
 
     private CheckId checkId;
 
+    /**
+     * Checks if a Checkable, or any Object in its datastructure, contains a specific error.
+     * <p>
+     * Terminates early upon finding the error by throwing {@link CheckErrorFound}
+     *
+     * @param checkable       The object to check
+     * @param checkIdentifier The specific error's associated ID
+     * @throws CheckErrorFound when the error is found
+     */
     public static void checkObject(Checkable checkable, CheckId checkIdentifier) throws CheckErrorFound {
         checkable.accept(new ContainsErrorVisitor(checkIdentifier));
     }

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/utils/visitors/GmlGeometryRebuilder.java

@@ -5,12 +5,26 @@ import de.hft.stuttgart.citydoctor2.datastructure.CityObject;
 import de.hft.stuttgart.citydoctor2.parser.ParserConfiguration;
 import org.citygml4j.core.util.geometry.GeometryFactory;
 
+import java.util.Objects;
+
+/**
+ * This Visitor recreates the Geometries of the original CityGml object from the associated Geometries in CityDoctor's
+ * internal model.
+ */
 public class GmlGeometryRebuilder extends AbstractCheck {
 
     private final GeometryFactory factory;
     private final ParserConfiguration config;
 
+    /**
+     * Creates a new Rebuilder for reconstruction of CityGml geometries.
+     *
+     * @param factory       the GeometryFactory used for creation of CityGml geometry objects.
+     * @param configuration the configuration settings of the parser
+     */
     public GmlGeometryRebuilder(GeometryFactory factory, ParserConfiguration configuration) {
+        Objects.requireNonNull(factory);
+        Objects.requireNonNull(configuration);
         this.factory = factory;
         this.config = configuration;
     }

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/utils/visitors/PrepareForCheckingVisitor.java

@@ -3,6 +3,9 @@ package de.hft.stuttgart.citydoctor2.utils.visitors;
 import de.hft.stuttgart.citydoctor2.check.AbstractCheck;
 import de.hft.stuttgart.citydoctor2.datastructure.Geometry;
 
+/**
+ * This Visitor prepares the {@link Geometry Geometries} in a Checkable for low-memory consumption mode.
+ */
 public class PrepareForCheckingVisitor extends AbstractCheck {
 
     @Override

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/utils/visitors/UnsetGeometriesVisitor.java

@@ -3,6 +3,10 @@ package de.hft.stuttgart.citydoctor2.utils.visitors;
 import de.hft.stuttgart.citydoctor2.check.AbstractCheck;
 import de.hft.stuttgart.citydoctor2.datastructure.CityObject;
 
+/**
+ * This Visitor removes the GmlGeometries from the linked original GmlObjects in a CityObject's datastructure to reduce
+ * memory bloat.
+ */
 public class UnsetGeometriesVisitor extends AbstractCheck {