[javadoc] Replace < > in pre/code tags automatically

[laeubi]

Today I noticed that JD replaces @ in javadoc code/pre tags automatically to @ as these needs to be escaped on save the file that is great help already 👍 .

Sadly it seem to not do the same for < (=<) and > (=>) leading to even JDT is suffering from such faulty javadoc:

• Javadoc issues eclipse.jdt.core#1582

a similar issue seem to exits with & (=&)

FYI @jukzi @akurtakov

[jukzi]

Do you mean <code>mytext</code> or {@code mytext} blocks? Please give a reference to a specification what should be done.

[jukzi]

if eclipse-jdt/eclipse.jdt.core#1583 is fixed the javdoc should use {@snippet instead of code and pre

[akurtakov]

Snippet is added in Java 18 which means our builds will have to start using Java 21 (first LTS that has support for snippet). IMHO, it's something we should done ASAP.

[laeubi]

I dont understnad what you mean by "specification" maybe something like that that also mention that @, < > and & are special: https://blogs.oracle.com/javamagazine/post/java-javadoc-snippet.

Migration to @snippet might be nice but does not solve the issue for older jvms, to reproduce do the following:

Create a new class, maybe like this:

/**
 * Hello JavaDoc
 *
 * <pre>
 *
 * </pre>
 */
public class JavaDocTest {

}

now add inside the pre tags @HelloEscape like this

/**
 * Hello JavaDoc
 *
 * <pre>
 *  @HelloEscape
 * </pre>
 */
public class JavaDocTest {

}

on save (for equinox not sure how /what they enabled in the settings to do so!)

I end up with:

/**
 * Hello JavaDoc
 *
 * <pre>
 *  &#64;HelloEscape
 * </pre>
 */
public class JavaDocTest {

}

(see for example https://github.com/eclipse-equinox/equinox/pull/415/files#diff-4ebbd2f0859833c456d338ad6a4afbe98e876ac305ed74b93336c0cb5a1f73fb )

but using

/**
 * Hello JavaDoc
 *
 * <pre>
 *  @HelloEscape
 * <ThisIsNotEscaped>
 * And & not as well
 * </pre>
 */
public class JavaDocTest {

}

results in

/**
 * Hello JavaDoc
 *
 * <pre>
 *  &#64;HelloEscape
 * <ThisIsNotEscaped>
 * And & not as well
 * </pre>
 */
public class JavaDocTest {

}

Actually I think regardless of settings special char should always be escaped and of course all of them...