RFR: 7903639: Add javadoc to all jextract generated API points

[Jorn Vernee]

On Tue, 23 Jan 2024 17:53:01 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This PR adds simple javadoc text to all the helper functions generated by jextract:
> * struct allocation methods
> * struct slicing methods
> * struct reinterpret methods
> * function pointer allocation method
> * function pointer invoke method
> 
> Following some offline discussions, I've decided to keep the comments very dry and simple (to avoid copying reams and reams of text into multiple classes). Also, the javadoc does not contain any `@param` or `@return` tag.

Marked as reviewed by jvernee (Committer).

src/main/java/org/openjdk/jextract/impl/FunctionalInterfaceBuilder.java line 83:

> 81: 
> 82:             /**
> 83:              * Allocates a new upcall segment, whose implementation is defined by {@code fi}.

Not sure about the "upcall segment" terminology here. This seems new. Why not just "upcall stub"?

src/main/java/org/openjdk/jextract/impl/FunctionalInterfaceBuilder.java line 102:

> 100: 
> 101:             /**
> 102:              * Invoke the upcall segment {@code funcPtr}, with given parameters

Same here

src/main/java/org/openjdk/jextract/impl/StructBuilder.java line 231:

> 229:             /**
> 230:              * Obtains a slice of {@code arrayParam} which selects the array element at {@code index}.
> 231:              * The returned segment has address {@code arrayParam.address() + index * layout().byteSize}

Suggestion:

             * The returned segment has address {@code arrayParam.address() + index * layout().byteSize()}

-------------

PR Review: https://git.openjdk.org/jextract/pull/193#pullrequestreview-1839688687
PR Review Comment: https://git.openjdk.org/jextract/pull/193#discussion_r1463847352
PR Review Comment: https://git.openjdk.org/jextract/pull/193#discussion_r1463847431
PR Review Comment: https://git.openjdk.org/jextract/pull/193#discussion_r1463848021