docs: review and improve package-info.java files across all modules

Bring all package-info.java files up to date with the actual package
contents, add missing ones for test-only packages.

Author: spannm

iban-commons-junit/src/main/java/de/speedbanking/iban/junit/jupiter/params/provider/package-info.java

@@ -1,19 +1,3 @@
-/*
- * Copyright © 2025-2026 Markus Spann, SpeedBankingDe
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 /**
  * JUnit 5 argument providers for IBAN-related parameterized tests.
  * <p>

iban-commons-validation/src/main/java/de/speedbanking/validation/package-info.java

@@ -2,6 +2,13 @@
  * Core package for Jakarta Bean Validation constraints and validators for IBAN and BIC.
  * <p>
  * Provides annotations such as {@link de.speedbanking.validation.ValidIban} and
- * {@link de.speedbanking.validation.ValidBic} to enforce proper financial data format and checksums.
+ * {@link de.speedbanking.validation.ValidBic} to enforce proper financial data format and
+ * checksums. {@code null} and empty values are considered valid by both constraints; combine
+ * with {@code @NotNull} or {@code @NotBlank} to reject them. Constraint evaluation is delegated
+ * to {@link de.speedbanking.validation.IbanConstraintValidator} and
+ * {@link de.speedbanking.validation.BicConstraintValidator}, which reuse the validation engines
+ * from {@code iban-commons}.
+ *
+ * @since 1.8.0
  */
 package de.speedbanking.validation;

iban-commons/src/main/java/de/speedbanking/bic/package-info.java

@@ -1,5 +1,14 @@
 /**
- * Provides classes for BIC validation and handling.
- * This includes the main {@link de.speedbanking.bic.Bic} model and its validator components.
+ * Core package for Business Identifier Code (BIC / SWIFT Code) representation and validation
+ * according to <strong>ISO 9362</strong>.
+ * <p>
+ * Central entry point is the immutable {@link de.speedbanking.bic.Bic} model, created via its
+ * static factory methods after successful validation by {@link de.speedbanking.bic.BicValidator}.
+ * Validation failures are reported either as a {@link de.speedbanking.bic.BicValidationResult}
+ * (non-throwing) carrying a {@link de.speedbanking.bic.BicValidationError}, or as an
+ * {@link de.speedbanking.bic.InvalidBicException} for the strict factory methods.
+ * {@link de.speedbanking.bic.RandomBic} generates syntactically valid BICs for testing purposes.
+ *
+ * @since 1.8.0
  */
 package de.speedbanking.bic;

iban-commons/src/main/java/de/speedbanking/iban/package-info.java

@@ -1,5 +1,28 @@
 /**
- * Core package for IBAN representation, validation, and registry services.
- * Includes support for deriving lookup keys for international banking services.
+ * Core package for International Bank Account Number (IBAN) representation, validation, and
+ * registry services according to <strong>ISO 13616</strong>.
+ * <p>
+ * Central entry point is the immutable {@link de.speedbanking.iban.Iban} model. Its structural
+ * rules per country are held by {@link de.speedbanking.iban.IbanRegistry}, which also provides
+ * access to {@link de.speedbanking.iban.IbanBuilder country builders} for constructing IBANs from
+ * their components. Validation is performed by {@link de.speedbanking.iban.IbanValidator} through
+ * a fail-fast pipeline of country-specific {@link de.speedbanking.iban.CountryValidator}
+ * implementations (see {@link de.speedbanking.iban.CountryValidators}), optionally combined with a
+ * {@link de.speedbanking.iban.NationalCheckDigitCalculator} (see
+ * {@link de.speedbanking.iban.NationalCheckDigitCalculators}).
+ * <p>
+ * Further supporting classes:
+ * <ul>
+ *   <li>{@link de.speedbanking.iban.IbanConfig} – immutable, initialize-once global configuration.</li>
+ *   <li>{@link de.speedbanking.iban.Formatter} – formats a normalized IBAN into the standard
+ *       display form (space-separated groups).</li>
+ *   <li>{@link de.speedbanking.iban.RandomIban} – generates syntactically valid IBANs for testing.</li>
+ *   <li>{@link de.speedbanking.iban.IbanPlusKey} – derives lookup keys for the SWIFT IBAN Plus
+ *       service, supporting BIC derivation from an IBAN.</li>
+ *   <li>{@link de.speedbanking.iban.InvalidIbanException} – thrown by the strict
+ *       {@link de.speedbanking.iban.Iban#of(CharSequence)} factory method on validation failure.</li>
+ * </ul>
+ *
+ * @since 1.8.0
  */
 package de.speedbanking.iban;

iban-commons/src/main/java/de/speedbanking/iban/util/package-info.java

@@ -1,4 +1,12 @@
 /**
  * Internal utilities specifically designed for IBAN pattern processing and validation.
+ * <p>
+ * {@link de.speedbanking.iban.util.IbanCharType} classifies BBAN pattern placeholder characters
+ * (e.g. {@code n}, {@code a}, {@code c}), while
+ * {@link de.speedbanking.iban.util.IbanPatternConverter} translates a country's BBAN pattern into
+ * an equivalent regular expression. {@link de.speedbanking.iban.util.InvalidBaseException} is
+ * thrown when such conversions encounter an unsupported or malformed pattern.
+ *
+ * @since 1.8.0
  */
 package de.speedbanking.iban.util;

iban-commons/src/main/java/de/speedbanking/util/package-info.java

@@ -44,5 +44,7 @@
  *   <dd>Common interface implemented by validation error enumerations such as
  *     {@link de.speedbanking.iban.IbanValidationError} and {@link de.speedbanking.bic.BicValidationError}.</dd>
  * </dl>
+ *
+ * @since 1.8.0
  */
 package de.speedbanking.util;

iban-commons/src/test/java/de/speedbanking/iban/junit/jupiter/params/converter/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * JUnit 5 {@link org.junit.jupiter.params.converter.ArgumentConverter} implementations and their
+ * tests, used to convert string-based parameterized test arguments (e.g. {@code "x"}, {@code "ja"})
+ * into typed values such as {@code boolean}.
+ */
+package de.speedbanking.iban.junit.jupiter.params.converter;

iban-commons/src/test/java/de/speedbanking/test/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Shared test-only helper utilities used across the {@code iban-commons} test suites.
+ */
+package de.speedbanking.test;