search

eclipse-jdt / eclipse.jdt.ui

Eclipse Public License 2.0
36 stars 87 forks source link

[23] JEP 467: Render markdown doc comments #1472

Closed stephan-herrmann closed 1 month ago

stephan-herrmann commented 3 months ago

See https://github.com/eclipse-jdt/eclipse.jdt.core/issues/2429 and https://openjdk.org/jeps/467

This issue is to coordinate activities needed for rendering markdown documentation in the UI (hover / javadoc view).

It has been proposed to use Mylyn Wikitext for this purpose, which raises questions like moving that project to Eclipse Platform. There are transitive dependencies that must be carefully checked before such move.

Alternatively, I could imagine that plain rendering (to HTML?) could be delegated via a new extension point, so that the wikitext dependency (with all its transitive dependencies) could be kept separate from jdt.ui.

stephan-herrmann commented 3 months ago

Before creating a dependency on Mylyn Wikitext JDT / Platform would like to see the dependency on guava removed.

See

From briefly scanning a few uses of guava in wikitext I haven't yet found anything that would require rocket science...

stephan-herrmann commented 3 months ago

I had to replace https://github.com/eclipse-mylyn/org.eclipse.mylyn/pull/562 with https://github.com/eclipse-mylyn/org.eclipse.mylyn/pull/568 - let's hope this converges quickly.

@iloveeclipse I'm afraid more "organizational" steps are needed to enable JDT to consume mylyn wikitext. What would be the best approach to coordinate activities like release of mylyn wikitext (required?), adding required dependencies to eclipse-sdk-prereqs, etc.? Could you help coordinate (or point out which person / entity could help)?

I'm afraid these activities are already on the critical path towards releasing support for Java 23.

stephan-herrmann commented 3 months ago

There is a plan B, and I'm dumbfounded how could I have missed that:

In https://bugs.openjdk.org/browse/JDK-8316039 it says:

The implementation employs a third-party library, commonmark-java, to transform Markdown to HTML.

It's licenced under "BSD 2-Clause 'Simplified' License", see https://github.com/commonmark/commonmark-java/blob/main/LICENSE.txt

Advantages:

@iloveeclipse what steps would be needed to allow JDT to use this library?

iloveeclipse commented 3 months ago

what steps would be needed to allow JDT to use this library?

This is for JDT UI, Core and batch compiler, or for UI and Core parts only?

Batch compiler would probably need to embed the library, as it is in most cases used as a single jar. If so, later two would just import it from batch compiler which would export new packages.

If we don't plan to use in batch compiler, but in Core and UI only, we can either wrap the library in a dedicated bundle or embed in JDT Core amd export to others.

If the question is not about embedding the library, but only about licensing & shipping with SDK, I would redirect it to @merks and @akurtakov who most likely know the answer. I'm also not sure if that library must be wrapped as an OSGI bundle by Orbit or it has already proper manifest and could be "just" added to the target platform.

stephan-herrmann commented 3 months ago

what steps would be needed to allow JDT to use this library?

This is for JDT UI, Core and batch compiler, or for UI and Core parts only?

not for the batch compiler.

[,,,] we can either wrap the library in a dedicated bundle or embed in JDT Core amd export to others.

If the question is not about embedding the library, but only about licensing & shipping with SDK, I would redirect it to @merks and @akurtakov who most likely know the answer.

Embedding or separate bundle would both be fine by me. Either way licensing would of course be the first issue.

I'm also not sure if that library must be wrapped as an OSGI bundle by Orbit or it has already proper manifest and could be "just" added to the target platform.

I don't see a manifest but module-info.java (with no dependencies, only listing all exported packages).

merks commented 3 months ago

Orbit has this content:

image

They have of course been IP reviewed and approved. And yes, these need to be wrapped.

stephan-herrmann commented 3 months ago

Thanks @merks that's good news! And sorry I didn't look in Orbit myself :)

As for the wrapping: eclipse-sdk-prereqs already points to https://download.eclipse.org/tools/orbit/simrel/orbit-aggregation/milestone/S202406281210 and in there I can see a readily wrapped https://www.eclipse.org/downloads/download.php?file=/tools/orbit/simrel/orbit-aggregation/milestone/S202406281210/plugins/org.commonmark_0.22.0.v20240316-0700.jar so we should be all set! :tada:

Right?

merks commented 3 months ago

Yes, you can start to use this the same way as batik is being used and it's wrapped just as batik is wrapped. For inquiring minds, it's wrapped by this:

https://github.com/eclipse-orbit/orbit-simrel/blob/bac46507329fd2224c412d3ea202a1ce796576ef/maven-bnd/tp/MavenBND.target#L1419-L1518

Of course this will be updated whenever a new version shows up on Maven Central...

I'm generally the one keeping the target platform up-to-date so if you need help or have questions just ask. 😀

stephan-herrmann commented 1 month ago

Here are some sneak previews of this feature based on latest from JDT/Core and https://github.com/eclipse-jdt/eclipse.jdt.ui/pull/1587:

Markdown_class

Markdown_method

Note the free mix of markdown syntax with traditional javadoc tags.

stephan-herrmann commented 1 month ago

Initial implementation has been merged (https://github.com/eclipse-jdt/eclipse.jdt.ui/commit/b6d65147ae32a6f503450e8ecd1e7e2a3eb093a4)

If remaining problems are detected, those will be handled via new issues.

nlisker commented 3 weeks ago

@stephan-herrmann I know that this is only for doc comments, but can the solution be expanded to rendering md files (as in an editor)? Users can install the Mylyn plugin, but if a solution is included already, can it "just" be exposed?

stephan-herrmann commented 3 weeks ago

@stephan-herrmann I know that this is only for doc comments, but can the solution be expanded to rendering md files (as in an editor)? Users can install the Mylyn plugin, but if a solution is included already, can it "just" be exposed?

I believe these are (similar but) disjoint use cases:

Neither is mylyn wikitext able to handle Java files, javadoc tags etc., nor do we have a solution for wysiwyg editing of javadoc of any flavor.

So a single solution that serves all purposes is not in sight.

If you are proposing to add a read-only view of pure .md files, such a view could be implemented using the commonmark plugins, used also for doc comments, but that would still be a new view, with no clear connection to Java / JDT.

If significant benefit over installing mylyn wikitext exists (does it?) then such view could be proposed as a small new plugin under the Platform/UI umbrella.