[foreign-abi] RFR: 8248560: Specify the behaviour of the ForeignLinker returned by CSupport::getSystemLinker [v2]

[Maurizio Cimadamore]

On Tue, 15 Sep 2020 20:33:53 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ForeignLinker.java line 35:
>> 
>>> 33:  * methods as a native function pointer (modelled as a {@link MemorySegment}).
>>> 34:  *
>>> 35:  * Instances of this interface can be obtained for instance by calling {@link CLinker#getSystemLinker()}
>> 
>> This comments should says something else - e.g. ```
>> Subclasses of this interface provide support for different linking strategies. For instance, the {@link CLinker}
>> interface defines a foreign linker which supports the C ABI.```
>
> We are in a situation where we have an interface and only one implementation (`CLinker`) - should we just have the
> latter, and maybe reserve the room to add the general interface at a later time, as we have more implementations?
> @PaulSandoz - what do you think?  We started off in this direction because we thought that it might have been useful to
> have different places where to document general foreign linker functionality - as opposed to functionalities that are
> only applicable to the C linker - but the interface is so general that I'm not sure exactly what we can say at this
> level.

We also need a comment about sealedness and immutability here

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

PR: https://git.openjdk.java.net/panama-foreign/pull/327