[23] Partition support for markdown comments #1542

[jarthana]

What it does

Fixes #1542

How to test

Author checklist

• I have thoroughly tested my changes
• The change is following the coding conventions
• I have signed the Eclipse Contributor Agreement (ECA)

[jarthana]

@ktatavarthi Can you please point me to the relevant test suits where I can find examples and add new tests?

[stephan-herrmann]

It seems with pulling this change all markdown comments in the editor lose their coloring. Is this intended? Will you add new colors / preferences?

Or should be declare that javadoc == javadoc, independent of format? (At face value we're mainly replacing HTML with markdown, but it's still javadoc, right?).

Or should we use colors to remind users of which format they are seeing, so they won't accidentally mix both?

[jarthana]

It seems with pulling this change all markdown comments in the editor lose their coloring. Is this intended? Will you add new colors / preferences?

Not intentional. I will work on this.

Or should be declare that javadoc == javadoc, independent of format? (At face value we're mainly replacing HTML with markdown, but it's still javadoc, right?).

Or should we use colors to remind users of which format they are seeing, so they won't accidentally mix both?

I would keep it simple and use the same color as Javadoc, at least for now.

[stephan-herrmann]

not related to this change: it looks like #1011 forgot to fix this version during move to another plugin. core.manipulation has no 3.20 to match this.

[stephan-herrmann]

There's some inconsistency:

• the processor is registered for markdown partition
• the ctor of JavadocCompletionProcessor still associates it to the javadoc partition

When I tweak JavadocCompletionProcessor to pass the markdown partition into the super ctor, then no proposals will be shown in markdown any more.

IIUC, the reason is that plugin.xml does not associate any proposal computer with the markdown partition type.

Suggestion: add a parameter partition to the ctor of JavadocCompletionProcessor, then selectively add markdown partition in plugin.xml. This should give us control to enable desired processors while excluding, e.g., HTMLTagCompletionProposalComputer.

[jarthana]

In order to boost my confidence in this area (and to get this code to a build), I will take this up also as part of my next iteration.

[stephan-herrmann]

Unsorted observations & ideas while playing with this PR and stepping through code:

• would it be interesting to define yet another partition type "codeblock within markdown"?
• I like the auto insertion of "///", how hard would it be to let this add as many blanks as the least indented line so far, minimally 1 (per convention)?
• folding completely hides the markdown region, whereas traditional javadoc will still show the first line
• seeing a change in CodeTemplateSourceViewerConfiguration (related to editing comment templates) lets me think we might want a full new set of comment templates in the future ...
• shift-hover over markdown link works, cool! ✔️

Concerning completion:

• completion for @param works, both tag name and actual parameter name are proposed. ✔️
• java templates are also proposed which is not useful
  • not a big issue, but at least priorities could be improved to show tag proposals above java templates
• after @param also HTML tags are proposed, which is not helpful
• I don't yet get the expected proposals after [
• After [# it proposes to insert {@link #foo()}, which is not what I want :), I want [#foo()]
  works mostly, see next comment ✔️

In summary: I could not find any obvious bugs, so the PR can be seen as an incremental step forward. I don't think all of the above topics need to be dealt with while this is a preview feature.

• Perhaps the last item (completion after [) would be highest on my list, but then this needs to be addressed in jdt.core, not ui.
  -> corner cases addressed in [23] Code assist changes for markdown Javadoc comments eclipse.jdt.core#2861
• On the UI side, perhaps folding (showing one line when folded) would be my first wish.
• For auto-insertion I'd suggest to just constantly insert one blank for now, to make it /// .

[stephan-herrmann]

After [# it proposes to insert {@link #foo()}, which is not what I want :), I want [#foo()]

This actually worked already in many cases. Just some edge-conditions need slight improvement, see eclipse-jdt/eclipse.jdt.core#2861

[stephan-herrmann]

@jarthana given that [] pairs are relevant for link completion I figured we should let smart-insert for brackets work in markdown partitions, too. The following seems to do the trick already:

diff --git a/org.eclipse.jdt.ui/ui/org/eclipse/jdt/internal/ui/javaeditor/CompilationUnitEditor.java b/org.eclipse.jdt.ui/ui/org/eclipse/jdt/internal/ui/javaeditor/CompilationUnitEditor.java
index bf6465b..716be39 100644
--- a/org.eclipse.jdt.ui/ui/org/eclipse/jdt/internal/ui/javaeditor/CompilationUnitEditor.java
+++ b/org.eclipse.jdt.ui/ui/org/eclipse/jdt/internal/ui/javaeditor/CompilationUnitEditor.java
@@ -532,7 +532,7 @@
 				}
 
 				ITypedRegion partition= TextUtilities.getPartition(document, IJavaPartitions.JAVA_PARTITIONING, offset, true);
-				if (!IDocument.DEFAULT_CONTENT_TYPE.equals(partition.getType()))
+				if (!IDocument.DEFAULT_CONTENT_TYPE.equals(partition.getType()) && !IJavaPartitions.JAVA_MARKDOWN_COMMENT.equals(partition.getType()))
 					return;
 				if (!validateEditorInputState())
 					return;

Do you want to adopt this in your current change?

[jarthana]

* On the UI side, perhaps folding (showing one line when folded) would be my first wish.

The PR addresses this now.