Update README.mds and javadocs

Author: malczuuu

README.md

@@ -561,8 +561,7 @@ to resolve to proper HTTP links dynamically.
 Property that defines a template for overriding the `"type"` field in `Problem` responses. The value may contain special
 placeholders that will be replaced at runtime:
 
-- `{problem.type}` — the original problem’s `"type"` value
-- `{context.traceId}` — the current request’s trace identifier (if available)
+- `{problem.type}` — the original problem’s `"type"` value.
 
 Defaults to `null` (no override applied). This can be used to unify or enrich problem type URIs across the application.
 
@@ -574,6 +573,9 @@ Defaults to `null` (no override applied). This can be used to unify or enrich pr
 > 
 > the post processor will change `"type"` value to `"https://errors.example.com/problems/validation`.
 
+This feature will override original type only if resulting `type` will not be empty. Note that the resulting `type` must
+be a valid URI.
+
 ### `problem4j.instance-override`
 
 This property allow overriding the `"instance"` field of `Problem` responses with custom templates at the environment
@@ -583,8 +585,8 @@ enabling them to resolve to proper HTTP links dynamically.
 Property that defines a template for overriding the `"instance"` field in `Problem` responses. The value may contain
 special placeholders that will be replaced at runtime:
 
-- `{problem.instance}` — the original problem’s `"instance"` value
-- `{context.traceId}` — the current request’s trace identifier (if available)
+- `{problem.instance}` — the original problem’s `"instance"` value,
+- `{context.traceId}` — the current request’s trace identifier (if available).
 
 Defaults to `null` (no override applied). This is useful for controlling how problem instances are represented in your
 API responses, even without tracing enabled.
@@ -599,6 +601,9 @@ API responses, even without tracing enabled.
 > 
 > For using `{problem.instance}` placeholder, the `instance` field will behave similarly to `type-override`.
 
+This feature will override original `instance` only if resulting type will not be empty. Note that the resulting
+`instance` must be a valid URI.
+
 ### `problem4j.resolver-caching.enabled`
 
 Enables caching of resolved `ProblemResolver` instances to avoid repeated reflection and lookup. Defaults to `false`
@@ -608,7 +613,7 @@ stable set of exception / resolver types.
 ### `problem4j.resolver-caching.max-cache-size`
 
 Maximum number of resolver entries stored when caching is enabled. Defaults to `128`. Uses LRU (least recently used)
-eviction once the limit is exceeded. Values `<= 0` mean the cache is unbounded (no eviction) – use cautiously if many
+eviction once the limit is exceeded. Values `<= 0` mean the cache is unbounded (no eviction) - use cautiously if many
 distinct resolver types may appear.
 
 Example:
@@ -620,7 +625,7 @@ problem4j.resolver-caching.max-cache-size=256
 
 Notes:
 
-- If you rarely introduce new resolver types, a small cache (64–256) is usually enough.
+- If you rarely introduce new resolver types, a small cache (64-256) is usually enough.
 - Leave disabled if startup / reflection cost is negligible or resolver set is highly dynamic.
 
 ## FAQ

problem4j-spring-bom/README.md

@@ -0,0 +1,67 @@
+# BOM of Problem4J
+
+Bill Of Materials (BOM) for the Spring integrations of **Problem4J**, a library implementing *RFC 7807 - Problem Details
+for HTTP APIs*.
+
+Importing this BOM lets you declare the individual `problem4j-*` Spring modules **without repeating versions** and keeps
+all components aligned.
+
+## Using the BOM
+
+### Gradle (Kotlin DSL)
+
+Add the BOM to `implementation(platform(...))`, then declare modules without versions.
+
+```kotlin
+dependencies {
+    implementation(platform("io.github.malczuuu.problem4j:problem4j-spring-bom:1.0.0-rc2"))
+
+    implementation("io.github.malczuuu.problem4j:problem4j-core")
+    implementation("io.github.malczuuu.problem4j:problem4j-jackson")
+    implementation("io.github.malczuuu.problem4j:problem4j-spring-web")
+    implementation("io.github.malczuuu.problem4j:problem4j-spring-webmvc")
+    implementation("io.github.malczuuu.problem4j:problem4j-spring-webflux")
+}
+```
+
+### Maven
+
+Add the BOM to `<dependencyManagement>` with `import` scope, then declare modules without versions.
+
+```xml
+
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>io.github.malczuuu.problem4j</groupId>
+            <artifactId>problem4j-spring-bom</artifactId>
+            <version>1.0.0-rc2</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+
+<dependencies>
+<dependency>
+    <groupId>io.github.malczuuu.problem4j</groupId>
+    <artifactId>problem4j-core</artifactId>
+</dependency>
+<dependency>
+    <groupId>io.github.malczuuu.problem4j</groupId>
+    <artifactId>problem4j-jackson</artifactId>
+</dependency>
+<dependency>
+    <groupId>io.github.malczuuu.problem4j</groupId>
+    <artifactId>problem4j-spring-web</artifactId>
+</dependency>
+<dependency>
+    <groupId>io.github.malczuuu.problem4j</groupId>
+    <artifactId>problem4j-spring-webmvc</artifactId>
+</dependency>
+<dependency>
+    <groupId>io.github.malczuuu.problem4j</groupId>
+    <artifactId>problem4j-spring-webflux</artifactId>
+</dependency>
+</dependencies>
+```

problem4j-spring-web/src/main/java/io/github/malczuuu/problem4j/spring/web/annotation/DefaultProblemMappingProcessor.java

@@ -96,13 +96,18 @@ public boolean isMappingCandidate(Throwable t) {
     return t != null && t.getClass().isAnnotationPresent(ProblemMapping.class);
   }
 
+  /** Returns the {@link ProblemMapping} annotation from the class if present, otherwise null. */
   private ProblemMapping findAnnotation(Class<?> clazz) {
     if (clazz == null) {
       return null;
     }
     return clazz.getAnnotation(ProblemMapping.class);
   }
 
+  /**
+   * Applies the "type" value from {@link ProblemMapping#type()} after placeholder interpolation;
+   * ignores invalid URIs.
+   */
   private void applyTypeOnBuilder(
       ProblemBuilder builder, ProblemMapping mapping, Throwable t, ProblemContext context) {
     String rawType = mapping.type() == null ? "" : mapping.type().trim();
@@ -118,6 +123,7 @@ private void applyTypeOnBuilder(
     }
   }
 
+  /** Applies the interpolated title if present and non-empty. */
   private void applyTitleOnBuilder(
       ProblemBuilder builder, ProblemMapping mapping, Throwable t, ProblemContext context) {
     String titleRaw = mapping.title() == null ? "" : mapping.title();
@@ -129,12 +135,14 @@ private void applyTitleOnBuilder(
     }
   }
 
+  /** Sets the HTTP status when greater than zero. */
   private void applyStatusOnBuilder(ProblemMapping mapping, ProblemBuilder builder) {
     if (mapping.status() > 0) {
       builder.status(mapping.status());
     }
   }
 
+  /** Applies the interpolated detail text if non-empty. */
   private void applyDetailOnBuilder(
       ProblemBuilder builder, ProblemMapping mapping, Throwable t, ProblemContext context) {
     String detailRaw = mapping.detail() == null ? "" : mapping.detail();
@@ -146,6 +154,7 @@ private void applyDetailOnBuilder(
     }
   }
 
+  /** Applies the interpolated instance value; ignores invalid URIs. */
   private void applyInstanceOnBuilder(
       ProblemBuilder builder, ProblemMapping mapping, Throwable t, ProblemContext context) {
     String rawInstance = mapping.instance() == null ? "" : mapping.instance().trim();
@@ -161,6 +170,7 @@ private void applyInstanceOnBuilder(
     }
   }
 
+  /** Adds extension fields resolved from {@link ProblemMapping#extensions()}. */
   private void applyExtensionsOnBuilder(
       ProblemBuilder builder, ProblemMapping mapping, Throwable t) {
     String[] extensions = mapping.extensions();
@@ -179,10 +189,15 @@ private void applyExtensionsOnBuilder(
   }
 
   /**
-   * Interpolate placeholders of form {name}. Special forms: - {message} - {context.key} -
-   * {context.traceId} (shorthand for {context.traceId}) - other names: looks for instance field.
+   * Interpolates placeholders of the form {@code {name}}. Supported keys:
+   *
+   * <ul>
+   *   <li>{@code message} - throwable message
+   *   <li>{@code context.traceId} - trace ID from context
+   *   <li>Any other token - value of a matching field in the throwable class hierarchy
+   * </ul>
    *
-   * <p>If a placeholder resolves to null - it's replaced by empty string.
+   * Missing values resolve to an empty string.
    */
   private String interpolate(String template, Throwable t, ProblemContext context) {
     if (template == null) {
@@ -210,10 +225,7 @@ private String interpolate(String template, Throwable t, ProblemContext context)
     return sb.toString();
   }
 
-  /**
-   * Resolve a value for a placeholder name from the throwable or context. Checks only instance
-   * field (including private) and searches up class hierarchy.
-   */
+  /** Resolves a placeholder by reflective field lookup up the throwable class hierarchy. */
   private Object resolvePlaceholderSource(Throwable t, String name) {
     if (t == null || !StringUtils.hasLength(name)) {
       return null;

problem4j-spring-web/src/main/java/io/github/malczuuu/problem4j/spring/web/annotation/ProblemMappingProcessor.java

@@ -21,7 +21,7 @@
  * }
  * }</pre>
  *
- * <p>Implementations should return {@code null} if the exception class is not annotated with {@link
+ * <p>Implementations should return {@code null} if the exception class is not annotated with {@code
  * ProblemMapping}, and may throw {@link ProblemProcessingException} if an error occurs during
  * problem creation.
  *

problem4j-spring-web/src/main/java/io/github/malczuuu/problem4j/spring/web/annotation/ProblemProcessingException.java

@@ -7,22 +7,48 @@
  */
 public class ProblemProcessingException extends RuntimeException {
 
+  /** Creates a new exception with no detail message and no cause. */
   public ProblemProcessingException() {
     super();
   }
 
+  /**
+   * Creates a new exception with the specified detail message.
+   *
+   * @param message human-readable explanation of the failure
+   */
   public ProblemProcessingException(String message) {
     super(message);
   }
 
+  /**
+   * Creates a new exception wrapping the given cause.
+   *
+   * @param cause underlying cause (may be {@code null})
+   */
   public ProblemProcessingException(Throwable cause) {
     super(cause);
   }
 
+  /**
+   * Creates a new exception with the specified detail message and cause.
+   *
+   * @param message human-readable explanation
+   * @param cause underlying cause (may be {@code null})
+   */
   public ProblemProcessingException(String message, Throwable cause) {
     super(message, cause);
   }
 
+  /**
+   * Advanced constructor allowing full control over suppression and stack trace writability.
+   * Typically used only internally or in tests.
+   *
+   * @param message detail message
+   * @param cause underlying cause (may be {@code null})
+   * @param enableSuppression whether suppression is enabled or disabled
+   * @param writableStackTrace whether the stack trace should be writable
+   */
   protected ProblemProcessingException(
       String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
     super(message, cause, enableSuppression, writableStackTrace);

problem4j-spring-web/src/main/java/io/github/malczuuu/problem4j/spring/web/context/ProblemContextSettings.java

@@ -1,6 +1,22 @@
 package io.github.malczuuu.problem4j.spring.web.context;
 
+/**
+ * Settings used when building a {@link ProblemContext} for incoming requests.
+ *
+ * <p>Provides access to infrastructure configuration such as the HTTP header name that carries a
+ * trace identifier. Implementations are typically backed by external configuration (e.g. Spring
+ * Boot properties) and are expected to be thread-safe.
+ */
 public interface ProblemContextSettings {
 
+  /**
+   * Returns the name of the HTTP header that contains a trace / correlation ID.
+   *
+   * <p>The trace ID (if present) may be injected into generated Problem responses (e.g. via
+   * placeholders in instance/type override templates) and echoed back to clients to aid in log
+   * correlation and diagnostics.
+   *
+   * @return the tracing header name, or {@code null} if tracing is disabled / not configured
+   */
   String getTracingHeaderName();
 }

problem4j-spring-web/src/main/java/io/github/malczuuu/problem4j/spring/web/format/IdentityProblemFormat.java

@@ -3,6 +3,12 @@
 /** Convenience implementation for {@link ProblemFormat} which doesn't transform input data. */
 public class IdentityProblemFormat implements ProblemFormat {
 
+  /**
+   * Returns the input detail unchanged (identity formatting).
+   *
+   * @param detail original detail text (may be {@code null})
+   * @return the same {@code detail} value
+   */
   @Override
   public String formatDetail(String detail) {
     return detail;