Include code snippets in sources Jars about graal HOT 14 CLOSED

Hm, I kind of share the sentiment.
Not sure about the technical solution though. Seems problematic.

@jtulach, you got an idea?
Generally, I like that the code examples are checked by the compiler. With the changes we have this is absolutely necessary.

@pniederw, the relevant project is codesnippet4javadoc, pull requests are probably welcome.

from graal.

I agree. Its also my favorite way of browse external libraries and code in general. While I understand the advantages of codesnippets its lack of IDE support kills it.

from graal.

To be fair, after attaching Javadoc Jars to the IDE project (which at least Gradle doesn't do by default), documentation popup/window does reveal the sample code (in IntelliJ). But it's not the same experience as having it in the source code.

I do understand the need to manage code snippets externally, and it has a clear benefit for users (code is more likely to be correct). Personally I prefer to use Asciidoclet for this, but it suffers from the same problem.

There are two technical solutions I can think of:

1. Embed snippets in source code before compiling (perhaps only for published builds).
2. Improve IDEs to display Javadoc (e.g. taken from attached Javadoc Jar) in-place.

from graal.

I was hoping attaching Javadoc will solve the most critical problem.

from graal.

In the current situation for me the disadvantages outweigh the advantages. I'd rather live with the redundancy of having the test case defined in a TestClass as well.

from graal.

I don't have a strong opinion about the tradeoff here, but I disagree with the choice of keywords "BEGIN" and "END". They appears completely mysterious to the uninformed (human) reader, and we've seen examples in recent code reviews. Keywords that are more self-explanatory would help.

from graal.

@mlvdv +1

from graal.

I don't understand what is wrong on sentences like "begin of sample xyz" and "end of sample xyz", but you are of course allowed to propose alternatives. Contribute to development of the codesnippets plugin by forking https://github.com/jtulach/codesnippet4javadoc ...

from graal.

In order to proceed with this inquiry, we need a representative project to demonstrate the issues on. I suggest to use simplelanguage with [email protected] as that is the project users of Truffle API are supposed to start with and (unlike internal projects) it uses Java de-facto standard build system.

After opening it in my IDE and downloading Javadoc for its libraries (one click on node representing project dependencies) I can confirm the code snippet is properly included and displayed when reading documentation in IDE's code completion:

We should verify the same behavior is achievable in the other two supported IDEs when working with the simplelanguage project.

from graal.

@jtulach My comment about keywords "BEGIN" and "END" comes from finding the declarations of those snippets (in code), not in their use (in JavaDoc). A reader who doesn't know about this mechanism will have no clue about how to figure out why they are there.

from graal.

@chrisseaton inspired me in #40 to investigate what it would take to embed the code snippets directly in the API itself. If we do what Chris did and use @link instead of @codesnippet we'll get the same Javadoc and our IDEs will properly navigate from the Javadoc to the actual code snippet. Implemented as jtulach/codesnippet4javadoc@515fdd1

from graal.

Here is Truffle code base rewritten to use the new embedded style. As far as I can tell the navigation is now OK. For majority of the cases the "go to definition" jumps to proper place. For the more complex cases (TruffleLanguage referencing PolyglotEngine) "Go to type" dialog works in my IDE.

from graal.

Pull request for mx created: graalvm/mx#65

from graal.

#95 is merged. Closing. Enjoy navigable snippets!

from graal.