I would support this. I don’t actually mind reading unformatted javadoc that’s been written with a light touch, but I agree our normal usage is much more aligned with Markdown. I only lament that they choose triple slash as the prefix, but I have no doubt my tastes will adapt.
> On 2 Dec 2024, at 15:30, Branimir Lambov <blam...@apache.org> 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
