+1 for more code (github/ide) readable in-code documentation. Do we use javadoc anywhere anymore, or read its generated apidocs anywhere ? We removed that target from the build cycle, and don't publish those artefacts or deploy the apidocs anywhere anymore… I would say folk are either got the code, via git clone, direct on github, or via a sources jar in their ide.
On Mon, 2 Dec 2024 at 16:31, 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 >
