Support Markdown Documentation Comments (JEP 467, JDK 23)

[odenix]

Consider the following code:

import java.nio.ByteBuffer;

interface BufferAllocator {
  /// Returns a lease for a [ByteBuffer] with at least the specified [capacity][ByteBuffer#capacity].
  LeasedByteBuffer getByteBuffer(long minCapacity);
}

Formatting the above code causes the following issues:

1. The doc comment is split into two lines, but the second line starts with // instead of ///.
2. The import statement is removed, breaking the links.

Disabling Javadoc formatting doesn't prevent either issue. The only workaround I could find was to disable google-java-format.

Tested with JDK 23 and google-java-format 1.24.0.

[dweiss]

So we would like to move this forward somehow, since Apache Lucene (main branch) is on Java 23 already and will go to Java 24 as soon as it's released, probably.

An ideal way forward would be to format markdown nicely... but maybe a baby step of not touching any comment lines starting with /// would also do the job? I did a hacky experiment here -

https://github.com/google/google-java-format/compare/master...dweiss:google-java-format:preserve-markdown-like-lines

And it works like a charm, at least for me. I think in reality a line comment starting with a '/' is going to be a rare occurrence so the impact surface seems to be low... but I'm not the one to judge. Let me know if you'd like me to develop this further into a PR (so that the tests pass).

[dweiss]

I filed a PR here, all tests pass. #1231 I realize this isn't ideal, perhaps, but does the job. Let me know what you think.

[iNikem]

Team, any news on this issue? Or some attention to the proposed contribution solving it?

[sebersole]

@dweiss Have you by any chance published your fix anywhere?

[dweiss]

Other than the pull-request - no, I haven't published it anywhere, sorry. It is disappointing that not much is happening to support those markdown comments.