doc: migration to 4.x

- Add missing note on default annotation `value` attribute on `XXXParam`

Author: jknack

docs/asciidoc/migration/4.x.adoc

@@ -10,6 +10,23 @@ This is a **work in progress** document, if something is wrong or missing please
 
 - Java 21 as minimum
 
+==== Special HTTP names
+
+Starting from 4.0.7 `@XXXParam` the default annotation `value` attribute is actually that: *the default value*
+of the parameter. In previous version this was used it for `invalid/special HTTP names`.
+
+In 3.x:
+
+    @QuerParam("some-http-name") String name
+
+In 4.x
+
+    @QuerParam(name = "some-http-name") String name
+
+The `value` is now reserved for default values:
+
+    @QueryParam("20") int pageSize
+
 ==== Buffer API
 
 The package `io.jooby.buffer` is gone. It was replaced by `io.jooby.output` these classes

modules/jooby-apt/src/test/java/tests/i3836/C3836.java

@@ -0,0 +1,19 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package tests.i3836;
+
+import io.jooby.annotation.GET;
+import io.jooby.annotation.Path;
+import io.jooby.annotation.QueryParam;
+import tests.i3804.Base3804;
+
+@Path("/3836")
+public class C3836 extends Base3804 {
+  @GET("/attribute")
+  public String oddNameWithNameAttribute(@QueryParam(name = "some-http") String value) {
+    return value;
+  }
+}

modules/jooby-apt/src/test/java/tests/i3836/Issue3836.java

@@ -0,0 +1,30 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package tests.i3836;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+import io.jooby.apt.ProcessorRunner;
+
+public class Issue3836 {
+  @Test
+  public void shouldSupportNameAttribute() throws Exception {
+    new ProcessorRunner(new C3836())
+        .withSourceCode(
+            source -> {
+              System.out.println(source);
+              Assertions.assertTrue(
+                  source.contains(
+                      "return"
+                          + " c.oddNameWithNameAttribute(ctx.query(\"some-http\").valueOrNull());"));
+              Assertions.assertTrue(
+                  source.contains(
+                      "return"
+                          + " c.oddNameWithNameAttribute(ctx.query(\"some-http-named\").valueOrNull());"));
+            });
+  }
+}