search

eclipse-jdt / eclipse.jdt.core

Eclipse Public License 2.0
142 stars 112 forks source link

[23] JEP 467: Markdown Documentation Comments #2429

Open mpalat opened 1 month ago

mpalat commented 1 month ago

ref: https://openjdk.org/jeps/467

Summary Enable JavaDoc documentation comments to be written in Markdown rather than solely in a mixture of HTML and JavaDoc @-tags.

mpalat commented 1 week ago

Please check these -

  1. https://commonmark.org/ and https://github.com/commonmark/commonmark-spec/wiki/List-of-CommonMark-Implementations
akurtakov commented 1 week ago

There are both markdown and commonmark (for the subtle differences) implementations available in Eclipse Mylyn project (https://github.com/eclipse-mylyn/org.eclipse.mylyn/tree/main/mylyn.docs/wikitext/core) . This implementaiton is already used by LSP4E project so it might even be time to move a bundle or two to Eclipse Platform if it becomes requirement for both LSP4E and JDT. FYI @ruspl-afed

jarthana commented 1 week ago

Another point: If we were to use an existing bundle for implementation, we might have to move some of the code (for e.g. JavadocParser) from org.eclipse.jdt.core.compiler.batch to org.eclipse.jdt.core.

ruspl-afed commented 1 week ago

Thank you for referencing me @akurtakov

Regarding move of Wikitext from Eclipse Mylyn to Eclipse Platform: It does not look impossible, but it needs some third-party libraries that I would not welcome, like Guava.

stephan-herrmann commented 1 week ago

Another point: If we were to use an existing bundle for implementation, we might have to move some of the code (for e.g. JavadocParser) from org.eclipse.jdt.core.compiler.batch to org.eclipse.jdt.core.

I don't think any code in compiler.batch parses HTML, does it? It should be the same for markdown, then.

AFAICS all the interpretation of markup/down happens in jdt.ui, only. Am I missing anything?

iloveeclipse commented 1 week ago

AFAICS all the interpretation of markup/down happens in jdt.ui, only.

Nope. I recently had to fix org.eclipse.jdt.internal.core.JavadocContents and I believe there are few other places around that parse javadoc.

jarthana commented 1 week ago

Another point: If we were to use an existing bundle for implementation, we might have to move some of the code (for e.g. JavadocParser) from org.eclipse.jdt.core.compiler.batch to org.eclipse.jdt.core.

I don't think any code in compiler.batch parses HTML, does it? It should be the same for markdown, then.

AFAICS all the interpretation of markup/down happens in jdt.ui, only. Am I missing anything?

JavadocParser does quite a bit of work for this, for e.g. the Javadoc hover and view. There's some in jdt.ui, which are for partitions and such.

stephan-herrmann commented 1 week ago

So I stand corrected, jdt.core does a bit of HTML parsing.

But is it really done in the compiler?

iloveeclipse commented 1 week ago

I'm not sure when JavadocParser is called but looking at https://openjdk.org/jeps/467 it seems it is not only html to markdown is the problem but "classic" javadoc comment style /** */ is proposed to be replaced with /// - and that sounds like we need changes in batch compiler. Also links to symbols (types, methods, fields) are supposed to change to something like /// - [a field][String#CASE_INSENSITIVE_ORDER] which will most likely need some kind of compiler change.

stephan-herrmann commented 1 week ago

I'm not sure when JavadocParser is called but looking at https://openjdk.org/jeps/467 it seems it is not only html to markdown is the problem but "classic" javadoc comment style /** */ is proposed to be replaced with /// - and that sounds like we need changes in batch compiler. Also links to symbols (types, methods, fields) are supposed to change to something like /// - [a field][String#CASE_INSENSITIVE_ORDER] which will most likely need some kind of compiler change.

Correct, but still the compiler should not need to "understand" markdown. Also I assume interpreting the new link format will happen where HTML-anchors are handled now: in JavadocContents (i.e., model).

This would imply

In terms of architecture, my guess is still that only jdt.ui needs a new dependency.

stephan-herrmann commented 1 week ago

Also links to symbols (types, methods, fields) are supposed to change to something like /// - [a field][String#CASE_INSENSITIVE_ORDER] which will most likely need some kind of compiler change.

This, btw, is a bit tricky, because the link target may contain array types denoted with [], which requires some escaping to avoid confusion with the enclosing link syntax. This makes me think that hand coded parsing is most appropriate for this part.