Add documentation

backend/src/main/kotlin/app/ehrenamtskarte/backend/stores/importer/steps/FilterDuplicates.kt

@@ -7,6 +7,11 @@ import org.slf4j.Logger
 
 class FilterDuplicates(private val logger: Logger) : PipelineStep<List<AcceptingStore>, List<AcceptingStore>>() {
 
+    /**
+     * Filters the [input] and removes duplicates.
+     * For duplicates to be detected an exact match of name, postal code and street is necessary.
+     * The properties of the last accepting store are used if there are multiple valid properties.
+     */
     override fun execute(input: List<AcceptingStore>): List<AcceptingStore> {
         // Group by name + postal code + street to detect duplicates
         val groups = input.groupBy {

backend/src/main/kotlin/app/ehrenamtskarte/backend/stores/importer/steps/FilterLbe.kt

@@ -10,6 +10,10 @@ import org.slf4j.Logger
 class FilterLbe(private val logger: Logger): PipelineStep<List<LbeAcceptingStore>, List<LbeAcceptingStore>>() {
     private val invalidLocations = arrayOf("Musterhausen")
 
+    /**
+     * Filters the [input] and removes [LbeAcceptingStore] with invalid data.
+     * These are especially stores without name, location or an invalid category.
+     */
     override fun execute(input: List<LbeAcceptingStore>): List<LbeAcceptingStore> = input.filter { filterLbe(it) }
 
     private fun filterLbe(store: LbeAcceptingStore) = try {

backend/src/main/kotlin/app/ehrenamtskarte/backend/stores/importer/steps/MapFromLbe.kt

@@ -11,6 +11,11 @@ import org.apache.commons.text.StringEscapeUtils
 import org.slf4j.Logger
 
 class MapFromLbe(private val logger: Logger) : PipelineStep<List<LbeAcceptingStore>, List<AcceptingStore>>() {
+
+    /**
+     * Maps the [input] to [AcceptingStore].
+     * Properties are cleaned, decoded and converted to the correct types.
+     */
     override fun execute(input: List<LbeAcceptingStore>) = input.mapNotNull {
         try {
             AcceptingStore(

backend/src/main/kotlin/app/ehrenamtskarte/backend/stores/importer/steps/PostSanitizeFilter.kt

@@ -12,6 +12,10 @@ import org.slf4j.Logger
 class PostSanitizeFilter(private val logger: Logger, httpClient: HttpClient): PipelineStep<List<AcceptingStore>, List<AcceptingStore>>() {
     private val featureFetcher = FeatureFetcher(httpClient)
 
+    /**
+     * Filters the [input] preparing storing to the database.
+     * Stores without longitude, latitude or postal code or outside the states bounding box are removed.
+     */
     override fun execute(input: List<AcceptingStore>): List<AcceptingStore> = runBlocking {
         val stateBbox = featureFetcher.queryFeatures(listOf(Pair("state", STATE))).first().bbox
 

backend/src/main/kotlin/app/ehrenamtskarte/backend/stores/importer/steps/SanitizeAddress.kt

@@ -11,6 +11,11 @@ class SanitizeAddress(private val logger: Logger) : PipelineStep<List<AcceptingS
     private val houseNumberRegex = houseNumberRegex()
     private val postalCodeRegex = Regex("""[0-9]{5}""")
 
+    /**
+     * Sanitizes the addresses of the [input].
+     * Postal codes are mapped to either the first five digits (german postcode format) or null.
+     * Street and house numbers are correctly separated.
+     */
     override fun execute(input: List<AcceptingStore>) = input.mapNotNull {
         try {
             if (it.street?.contains(STREET_EXCLUDE_PATTERN) == true) return@mapNotNull it
@@ -42,6 +47,12 @@ class SanitizeAddress(private val logger: Logger) : PipelineStep<List<AcceptingS
         return Regex("""$prefix[0-9]+(($range)|($fraction)|($letter))?""")
     }
 
+    /**
+     * Correctly separates the street and house number properties.
+     * Excess information is moved to the [AcceptingStore.additionalAddressInformation] property.
+     * Examples: 'Untere'|'Zell' -> 'Untere Zell'|null, 'Am Römerbad 17'|'a' -> 'Am Römerbad'|'17 a',
+     *   'Rückermainstr. 2; 1.'|'OG' -> 'Rückermainstr.'|'2'|'1. OG'
+     */
     private fun AcceptingStore.sanitizeStreetHouseNumber(): AcceptingStore {
         val isStreetPolluted = street?.find { it.isDigit() } != null
         val isHouseNumberPolluted = houseNumber != null && !houseNumberRegex.matches(houseNumber)
@@ -73,6 +84,10 @@ class SanitizeAddress(private val logger: Logger) : PipelineStep<List<AcceptingS
         return this
     }
 
+    /**
+     * Maps the postal code to the first five digits or null.
+     * Examples: '86150' -> '86150', 'Augsburg 86161 Rathausplatz' -> '86161', 'A-1234' -> null
+     */
     private fun AcceptingStore.sanitizePostalCode(): AcceptingStore {
         val oldPostalCode = postalCode ?: return this
 

backend/src/main/kotlin/app/ehrenamtskarte/backend/stores/importer/steps/Store.kt

@@ -11,6 +11,10 @@ import org.slf4j.Logger
 
 class Store(private val logger: Logger, private val manualImport: Boolean) : PipelineStep<List<AcceptingStore>, Unit>() {
 
+    /**
+     * Stores the given [input] to the database.
+     * Longitude, latitude and postal code of [AcceptingStore] must not be null.
+     */
     override fun execute(input: List<AcceptingStore>) {
         transaction {
             try {
@@ -20,13 +24,9 @@ class Store(private val logger: Logger, private val manualImport: Boolean) : Pip
                 Addresses.deleteAll()
 
                 input.forEachIndexed { done, acceptingStore ->
-                    if (acceptingStore.postalCode == null) {
-                        logger.info("Skipping '${acceptingStore.name}' because its postal code is null.")
-                        return@forEachIndexed
-                    }
                     val address = AddressEntity.new {
                         street = acceptingStore.streetWithHouseNumber
-                        postalCode = acceptingStore.postalCode
+                        postalCode = acceptingStore.postalCode!!
                         locaction = acceptingStore.location
                         countryCode = acceptingStore.countryCode
                     }