javadoc Markdown issues

[nlisker]

Trying to use Markdown documentation, I came across quite a few issues with it. I'm not sure if this feature is still WIP from Eclipse's perspective (it was delivered in Java 23) and which of these is known, so here is a summary from which individual issues can be created:

• Javadoc view doesn't switch to MD docs when the cursor is placed in the docs area, unlike with HTML comments. The only way to switch to it is to click on the class name itself (for class docs).
• Javadoc view doesn't update in real time as text is being typed for MD, but does for HTML.
• Pressing enter while writing docs in MD places the caret (and the rest of the line) on the next line right after /// instead of 1 space after that, as it does with HTML's * .
• Auto complete is not triggered for links in MD as it does for HTML: Typing {@link Object# pops up the suggestions, but in MD [Object# does not. Pressing ctrl+space will bring up the suggestions, so there is recognition of the context (it just needs some encouragement).
• Typing apostrophe (') in MD creates an enclosing one as well, as if I'm typing a char in Java. This means that if I try to type it's it comes out as it's'.
• Typing 3 ` to start a codeblock and pressing enter does not automatically add a closing ```. Perhaps this is an enhancement request.
• Not sure if this is relevant for Eclipse, but syntax highlighting (```java or ```css) don't do anything. The JEP mentions external libraries being needed, but I wasn't sure if at least Java is automatically included. Perhaps it is a reasonable enhancement request to include java syntax coloring for JDT?
• I hit [23] Folding a markdown region hides the first line of subsequent Java code #1615 as well. My compliance level for the project is 23 (with and without preview features enabled).
• Using [i] inside a code block renders it as a broken link instead of literally:

  /// ```
  /// int i = 3;
  /// int[] d = new int[i];
  /// ```
  

  produces

  int i = 3;
  int[] d = new int<code><a href='eclipse-javadoc:%E2%98%82=bugs/src%3Cmarkdown%7BMDTest.java%E2%98%83MDTest%E2%98%82i'>i</a></code>;
  

• Formatting (ctrl+shift+F) does not do anything in MD, while in HTML it wraps a long line according to the formatter setting.

Tested with build id: I20241117-0600