Is there a dependency on Java 23 to make the `ant javadoc` tooling to work? My understanding is that this change is coming in the newer Java versions.
On 2024/12/02 15:30:14 Branimir Lambov wrote: > Hello, > > What is the community's stand on using the new Markdown variation of > JavaDoc? > https://docs.oracle.com/en/java/javase/23/javadoc/using-markdown-documentation-comments.html > > I find it as a dramatic improvement over the old style, which is very > unpleasant to write and close to unreadable anywhere we don't have proper > rendering (e.g. GitHub). Because of this, a lot of very detailed and > useable comments are written in something that is easy to read unformatted > and renders completely wrong when interpreted as JavaDoc. See e.g. > https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/utils/concurrent/Ref.java#L99 > https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/utils/concurrent/AsyncFuture.java#L46 > https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/db/tries/Trie.java#L143 > > Here's an example of how the Markdown style can be used: > https://github.com/apache/cassandra/blob/5d4c92b2ee543dadbb074cf14c2c451de9b7666b/src/java/org/apache/cassandra/db/lifecycle/CompositeLifecycleTransaction.java#L47 > > Because it is so much easier to write and is perfectly readable > unformatted, the new style should be more conducive to adding rich > documentation. As the comments are ignored by older compilers, the only > downside is that we would have to update tooling like `ant javadoc` to work > properly. IntelliJ already supports the new style and provides tooling to > convert existing comments to it. > > Regards, > Branimir >
