Some Javadoc links point to code snippets not included in any sources Jar

[pniederw]

This means that most Truffle users won't be able to navigate to these snippets in their IDE.

Cases I encountered:

• com.oracle.truffle.api.dsl.test.interop.Snippets.ExampleTruffleObject#getForeignAccessMethod
• com.oracle.truffle.api.dsl.test.interop.Snippets.ExampleTruffleObjectMR

[jtulach]

The interop example by @grimmerm has to deal with the tough situation that it is using an annotation processor. If we want the Snippets class to serve its purpose - e.g. really compile like the end user code compiles - it cannot be in the module that provides the annotation - as at the time when the module is being compiled, the annotation processor isn't yet ready to be used.

Non DSL based snippets don't suffer from this problem and are included next to their API.

[pniederw]

Another one:

• {@link com.oracle.truffle.api.vm.PolyglotEngineSnippets#initializeWithParameters}

Also, IntelliJ shows an error Cannot access com.oracle.truffle.api.TruffleLanguageSnippets.Context for the following snippet:

// @formatter:off
abstract
// BEGIN: TruffleLanguageSnippets.MyLanguage#createContext
class MyLanguage extends TruffleLanguage<Context> { ... }

[jtulach]

I am afraid I can't fix the IntelliJ error myself. You can report it to the IDE vendor or try to work around it yourself and attach a patch.

As far as can tell your comment about PolyglotEngineSnippets#initializeWithParameters concerns Env.getConfig() - alas, the snippet references PolyglotEngine and as such it has to be next to PolyglotEngine - otherwise we can't verify it compiles without errors.

[jtulach]

The philosophical question: Is it better to improve javadoc (as in jtulach@aa11550) and violate this co-location of code and sample snippets from time to time or do we rather have poorer Javadoc with less code snippets?

[smarr]

While I don't like it during browsing, IMHO broken examples are worse in the long term.

[jtulach]

+1 as the jtulach/truffle@aa11550 sample is super complex - it cross-cuts almost all layers of Truffle API. Having the sample in the TCK ensures it is used extensively, it is up-to-date, it not only compiles, but tests OK and works with all (TCK using) languages. In short that it properly represents its use-case.

[pniederw]

Ideally, for cases where co-location isn't feasible, use a form of inclusion other than @link. This will avoid any confusion why the link isn't working.

[jtulach]

The codesnippet 4 javadoc offers {@codesnippet reference} and it was used originally by Truffle. However as it is not recognized by the IDEs, it was replaced by the {@link .*Snippets.*} pattern. It is an interesting idea to use the original codesnippet tag for non-co-located samples. Of course still with the constraint that the reference is a fully qualified name that can be resolved by IDE like in jtulach@0e1b32f if all Truffle projects are open.

[chumer]

These links are not resolvable by all IDEs (It does not work for Eclipse). Especially like in the ExecWithTimeOut case where you link from API code into TCK code.

In case of ExecWithTimeOut it could be solved by moving the code closer to the javadoc. If an annotation processor is involved, its more difficult. In the case of Truffle DSL when you develop against the DSL API with the truffle-api.jar only, it would be very weird if we would link into projects that are not available. So I think, unless there is a better option, we should document these examples in the javadoc inline.

[jtulach]

I've just tried Eclipse Luna. Javadoc of prepareKill references com.oracle.truffle.tck.ExecWithTimeOut if I choose Navigate/GoTo/Type... and type in ExecWithTimeOut the IDE finds the right class with code snippet for me.

Of course, that isn't as comfortable as in NetBeans (where putting cursor on ExecWithTimeOut and pressing Ctrl+O is enough), but it is not that hard to do it. Right?

[chumer]

We worked around by making the source snippets navigable. Its not ideal, but it works. I don't have a better idea either.