On Fri, 31 Jul 2026 16:45:16 GMT, Joe Darcy <[email protected]> wrote:
>> Doc clarification. >> >> >> >> --------- >> - [x] I confirm that I make this contribution in accordance with the >> [OpenJDK Interim AI Policy](https://openjdk.org/legal/ai). > > Joe Darcy has updated the pull request incrementally with one additional > commit since the last revision: > > Fix typos found in code review. Some of the material on "structure" in the null-handling paragraph is germane to functional interfaces in general. I note that the package spec dances around the notion of structure vs semantics without mentioning it, and it also mentions "shape" without defining it. It would be helpful to address these in the main section of the package spec. With that in place, the null-handling paragraph no longer has the responsibility to address these topics, and it can be simplified. Here's a suggested draft for the main part of the package specification, to be placed before the current paragraph that begins, "The interfaces in this package are general purpose...." > A functional interface defines the <em>structure</em> of a function and not > its <em>semantics</em>. A function's structure is determined by the number > and types of the parameters and the return type of the functional method. > These are sometimes collectively referred to as the "shape" of the function. > The names of the functional interfaces, functional methods, and method > parameters are intended to be evocative of the function's shape, but these > names are not part of a function's shape, and they are not intended to imply > anything about the function's semantics. For example, the `Supplier` > interface is intended to be a function that in some sense supplies or > provides something, but it does not imply that anything was created. (One might ask where the semantics come from. I would say that the semantics are provided by the definition of an API that uses a functional interface, say in a method parameter or return type -- but those semantics apply only within that context. Maybe we should consider adding a small amount of material on this, but not if it threatens to go off into the weeds.) Given the above, the null handling policy can be changed to: > Because the functional interfaces in this package define only structure, > they impose no restrictions on the nullability of parameters and return > values of reference type. (We could further say that APIs that use functional interfaces may require parameters or return types to be non-null or otherwise mandate particular treatment of nulls.) I'm agnostic as to whether there needs to be a null-handling paragraph that is linked from all the different functional interfaces, or whether blanket statements such as the above in the package specification are sufficient. ------------- PR Comment: https://git.openjdk.org/jdk/pull/32111#issuecomment-5247165958
