It won’t work *properly* with current versions but the tooling should still handle it gracefully without blowing up. It just won’t generate the full docs. But arguably we don’t really care about that much - as other have mentioned, C* javadoc comments are mainly consumed from inside IDEs.
So might as well start writing javadoc in new code in this style. I’m actually going to start doing just that. > On 4 Dec 2024, at 16:58, Francisco Guerrero <fran...@apache.org> wrote: > > 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 >>
