You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cassandra.apache.org by Branimir Lambov <bl...@apache.org> on 2024/12/02 15:30:14 UTC
Markdown JavaDoc
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
Re: Markdown JavaDoc
Posted by Mick Semb Wever <mc...@apache.org>.
+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 <bl...@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
>
Re: Markdown JavaDoc
Posted by Benedict <be...@apache.org>.
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 <bl...@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
Re: Markdown JavaDoc
Posted by Aleksey Yeshchenko <al...@apple.com>.
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 <fr...@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
>>
Re: Markdown JavaDoc
Posted by Francisco Guerrero <fr...@apache.org>.
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
>