Comments (11)
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.
from graal.
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> { ... }
from graal.
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.
from graal.
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?
from graal.
While I don't like it during browsing, IMHO broken examples are worse in the long term.
from graal.
+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.
from graal.
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.
from graal.
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.
from graal.
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.
from graal.
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?
from graal.
We worked around by making the source snippets navigable. Its not ideal, but it works. I don't have a better idea either.
from graal.
Related Issues (20)
- InternalResourceCache is hard-coded to 'user.home'. Overriding the path fails in tests. HOT 6
- Error reading tcl file - Cannot read resource "/tcl/lang/library/init.tcl" HOT 1
- Make graalnodejs-community available in `nvm-sh/nvm` and `coreybutler/nvm-windows`
- [GR-51307] Unable to collect GC data with NotificationEmitter in native build HOT 6
- orai18n dependency causes native application startup failure - Missing character set id 560 HOT 10
- UnsatisfiedLinkError: No awt in java.library.path HOT 6
- Determine the locale of Native Image executables at run-time
- [GR-51862] Native image build fails when using quarkus and protobuf HOT 5
- Native image service unable to compress image HOT 1
- Warning caused by Truffle and Polyglot HOT 4
- GraalVM native with kotlin issue HOT 3
- A way to limit instructions per execution (mainly for wasm) HOT 3
- [GR-51934] MacOS UnsatisfiedLinkError: sun.security.krb5.SCDynamicStoreConfig.getKerberosConfig HOT 1
- [GR-52221] Allow native-image-plugin to use a docker image as executable HOT 2
- maven java app fail with 'Error: No main manifest attribute' HOT 2
- [GR-52220] Support for Cosmopolitan Libc HOT 4
- [GR-52023] Re-evaluate LibC.abort implementation HOT 2
- [GR-52021] Getting NullPointerException instead of something that tells me what is wrong HOT 9
- [GR-52067] Support `MemoryPoolMXBean` for G1 HOT 1
- Runtime exception when running Dotty's native image HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from graal.