correct the annotation positioning caveat for the six array columns

The comment in `generated/build.gradle.kts` and the section in `README.md`
claimed the annotation positions are correct because the generated code uses
no arrays. Six generated columns are arrays.

Java applies a `TYPE_USE` annotation written before an array type to the
element type, and NullAway drops array-dimension annotations in JSpecify mode.
So `@Nullable String[] getNspacl()` reads as a non-null array of nullable
strings, while the column is a nullable array of non-null strings. The six
accessors are `getNspacl`, `getDatacl`, `getRelacl`, `getReloptions`,
`getSetconfig` and `getDefaclacl`. No operator code calls them today, because
the operator uses the table field constants and `Routines.aclexplode` instead.

The README also claimed NullAway reads the real nullness of every generated
method. The generator annotates column accessors only. `Routines.java` and the
classes in the `routines` package carry no annotation, so a routine such as
`shobj_description` still counts as non-null.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: ThoSap

README.md

@@ -286,13 +286,20 @@ make generate-jooq
 ./gradlew :generated:jooqCodegen
 ```
 
-The generator writes JSpecify nullability annotations into the generated sources, so NullAway reads the real nullness of every generated method instead of guessing.  
-Two consequences are worth knowing:
+The generator writes JSpecify nullability annotations into the generated sources, so NullAway reads the real nullness of every generated column accessor instead of guessing.  
+Routine return values stay unannotated, so `Routines.shobjDescription` still counts as non-null even though PostgreSQL returns `NULL` for an object without a comment.  
+Three consequences are worth knowing:
 
 - jOOQ does not officially support the `TYPE_USE` positioning that JSpecify requires yet ([jOOQ/jOOQ#10759](https://github.com/jOOQ/jOOQ/issues/10759)).  
-  The positioning is correct here only because the generated code uses no generics, collections, maps, arrays or forced types with inner
+  The positioning is correct for every scalar column, because the generated code uses no generics, collections, maps or forced types with inner
   classes.  
   Keep the `includes` list free of such objects, or review the annotation positions after a regeneration.
+- The positioning is wrong for the six array columns.  
+  Java applies a `TYPE_USE` annotation written before an array type to the element type, and NullAway drops array-dimension annotations in `JSpecifyMode`.  
+  So `@Nullable String[] getNspacl()` reads as a non-null array of nullable strings, while the column is a nullable array of non-null strings.  
+  The six accessors are `getNspacl`, `getDatacl`, `getRelacl`, `getReloptions`, `getSetconfig` and `getDefaclacl`.  
+  No operator code calls them today, because the operator uses the table field constants and `Routines.aclexplode` instead.  
+  A declaration annotation for `nullableAnnotationType` would fix the positioning, because such an annotation always applies to the method. That is a design change.
 - Every generated class carries `@SuppressWarnings({"all", ...})`, which Error Prone honours.  
   That suppression, and nothing else, is why the generated sources are exempt from the checks in  `errorprone.args`, including `RequireExplicitNullMarking`.  
   Do not add `NullAway:TreatGeneratedAsUnannotated`: it would make NullAway discard the nullability annotations that this generator now writes.

generated/build.gradle.kts

@@ -54,8 +54,16 @@ jooq {
                 nullableAnnotation = true
                 // We use JSpecify annotations already even though jOOQ does not officially support JSpecify's TYPE_USE positioning yet.
                 // See https://github.com/jOOQ/jOOQ/issues/10759
-                // This only works as our generated code is not using any generics, collections, maps, arrays
-                // or forced types with inner classes, and therefore the positioning of the annotations is accidentally correct.
+                // The positioning is correct for every scalar column, as our generated code is not using any generics,
+                // collections, maps or forced types with inner classes.
+                // The positioning is wrong for the six array columns. Java applies a TYPE_USE annotation written before
+                // an array type to the element type, and NullAway drops array-dimension annotations in JSpecifyMode.
+                // So "@Nullable String[] getNspacl()" reads as a non-null array of nullable strings, while the column is
+                // a nullable array of non-null strings.
+                // The six accessors are getNspacl, getDatacl, getRelacl, getReloptions, getSetconfig and getDefaclacl.
+                // No operator code calls them today, as the operator uses the table field constants and Routines.aclexplode.
+                // A declaration annotation for nullableAnnotationType would fix the positioning, as such an annotation
+                // always applies to the method. That is a design change, not a comment fix.
                 nonnullAnnotationType = "org.jspecify.annotations.NonNull"
                 nullableAnnotationType = "org.jspecify.annotations.Nullable"
             }