On Mon, 13 Apr 2026 08:07:23 GMT, Jatin Bhateja <[email protected]> wrote:
>> Understand why short is used here as the current carrier type for the >> backing storage. My only concern is whether this implementation detail >> should be reflected directly in the Java API documentation. >> >> At the Java surface, Float16Vector reads as a vector of Float16 values >> (16-bit data in IEEE 754 binary16 format), not a vector of short values. I >> wonder whether the class-level doc should describe the semantic value type >> (Float16) and leave the carrier/storage detail to implementation notes >> instead. >> >> New here, so just my 2 cents. :-) > > Backing storage is a VM implementation level detail, even scalar Float16 API > documentation does not refer to short carrier type > https://docs.oracle.com/en/java/javase/26/docs/api/jdk.incubator.vector/jdk/incubator/vector/Float16.html > I have updated the documentation of public facing Float16Vector.fromArray API > to reflect existence of IEEE 754 binary16 encoded values being read from > short [] > > Kindly check. Sherman is right, we need to say a sequence of "16-bit data values in the IEEE 754 binary16 format.". Then we need to say that the element type is represented as `Float16`, but for operations accepting or producing element values or arrays the element type is represented as `short`, values of which hold 16-bit in the IEEE 754 binary16 format. We can refer users to other API points for producing/consuming those 16-bit data values. Then we can add an API note explaining the limitation - we cannot fully optimize values of `Float16` until it becomes a value type that is optimizable like values of `short`. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/28002#discussion_r3190537753
