JavaDoc Hits the Markdown on Comments - Inside Java Newscast #68

JavaDoc is our source of truth when comes to understanding in depth Java's API, but also an inspiration on how we can document our own code.
Creating code documentation involves writing a combination of custom JavaDoc tags and HTML elements, which can be time-consuming and error-prone due to its complexity.
Hence, let's take a sneak peek at JEP 467 and how Java documentation could be easier to read and maintain thanks to including Markdown syntax in comments.

*Links*

*Chapters*

0:00 Intro
0:53 Javadoc, JavaDoc, javadoc
2:25 A New Form of Comment
4:13 Syntactical Details and Beyond
6:33 Outro

*Tags* #Java #JDK #OpenJDK #JavaDoc

[JorgeEscobarMX]

I no longer program in java since 2018, but I appreciate the effort to finally bring markdown to it.

[loic.bertrand]

3:18 Why isn't the syntax for links [Text](url) ?

[scarletdice]

Love the Markdown, but I'm sure there's a better/prettier mechanism to mark it as a markdown instead of the triple slash.

[whiteyoghurt]

It could be cool to add UI for that. E.g.: right click on a method, select something like "Open Java Doc UI dialogue" - and the window would have text boxes for all the mentioned values - short description of what it does, table for example inputs and outputs, ...And it would generate thrown exceptions automatically from the method's signature (only checked exceptions), etc...

[PeterVerhas]

There is markdown doclet and Jamal doclet also supports markdown. It means yo do not need to wait for this jep.

[mm]

Sound quite interesting, will probably use it for sure!

[KangoV]

The 3 slashes (///) just looks bloody aweful! Much better to have
/*md
* ...
*/

[IvanToshkov]

I really like that we'll be able to use markdown for this. But what will happen when we decide to use something else? Markdown is good, but it's not flawless. Even its author has created a newer and arguably better alternative. With the current scheme we'll need to invent yet another way to specify doc strings format.

Also, the excessive hand-gesturing in the video makes me dizzy.

[withgrowinginsanity]

/// ''' 😢 '''
<pre> 😊 </pre>

[acerhigh]

markdown support should have been in the release for 14 years ago

[jackofnotrades]

JAVA still havent figured out how to create good documentation, even after 25 years...disappointing..😢

[yatsuk]

I guess these days majority of the documentation will be generated by AI. From this point of view it does not matter much what format it has - HTML or Markdown

[HighSurfUSA]

You speak too fast, this video is difficult to follow. Maybe someone else should do a better job at presenting this content.