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
