Better document relation with Factory10 interface and UnsupportedMessageException

[ldaynes]

The documentation for the Factory10 interface at the moment says that the accessXXX messages can return null if the message is not supported. However, example in SL shows that this is not done that way. Instead, the SL implementation always raise an UnsupportedMessageException (i.e., doing UnsupportedMessageException.raise(Message.XXX); )

Can you clarify in the documentation why is there two ways to do this and which one is the recommended one ?

[grimmerm]

Where does SL throw such an exception?
AFAIK, SL is using Interop-DSL, which generates a Factory10 implementation (which throws an UnsupportedMessageException).

@jtulach returning null is not a good idea - I think the JavaDoc of Factory10 is wrong.
One has to raise an UnsupportedMessageException (i.e., doing UnsupportedMessageException.raise(Message.XXX); ).

[ldaynes]

@grimmerm you can see throwing of these exception in the com.oracle.truffle.sl.runtime.SLxxxxMessageResolutionForeign classes. It's not clear that these are generated automatically -- nothing in the source indicate that, there's no @GeneratedBy or header comment telling so.

[woess]

Indeed, we should add a @GeneratedBy annotation. This also helps with navigating from the generated class to the source class in an IDE.

[chumer]

@grimmerm please fix this.

[jtulach]

Using @GeneratedBy is OK. Other option is to generate Javadoc and include @link references. Those are good for navigation as well.

[chumer]

There are currently no plans to fix this minor issue.