JavaDoc Hits the Markdown on Comments - Inside Java Newscast #68
Вставка
- Опубліковано 8 чер 2024
- 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
JEP 467: openjdk.org/jeps/467
CommonMark variant of Markdown: spec.commonmark.org/0.30
GitHub Flavored Markdown: github.github.com/gfm/#tables...
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 - Наука та технологія
nice to see a new face
sharing java updates.
no language ever had
stewardship this good.
I no longer program in java since 2018, but I appreciate the effort to finally bring markdown to it.
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...
3:18 Why isn't the syntax for links [Text](url) ?
Agree, the way they do it is no longer markdown.😢
Because the URL will be generated for you. You probably still get the links, but the [#method(String, etc)] syntax will generate something like [Class.method](url/to/doc). It's probably just extension of md, not a replacement for links.
@@sarabwtoh okay, thanks! I always swap parentheses and square brackets by mistake anyway x) so it's not necessarily a bad idea haha
I thought the same thing.
Love the Markdown, but I'm sure there's a better/prettier mechanism to mark it as a markdown instead of the triple slash.
Maybe with three stars /*** Markdown JavaDoc Comment */ would be better
@@kosiuty they probably needed something that would be ignored by older versions of the Javadoc compiler.
they could invent anything and defaults to the javadoc for backward compatibilities, just not the triple slash please.
There is markdown doclet and Jamal doclet also supports markdown. It means yo do not need to wait for this jep.
Sound quite interesting, will probably use it for sure!
/// ''' 😢 '''
😊
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.
IDEs also need to be able to parse the documentation. I don't think there will be a need for “even better” documenting any time soon. If your organization has specific needs, you can still have your own doclet to change how documentation is generated. Take inspiration from Asciidoclet and the Asciidoclet IntelliJ plugin ...
@ I'm not saying that it needs to support plugins or custom formats. But I think there might be a need for another official one in the not so distant future and there's no obvious upgrade path.
markdown support should have been in the release for 14 years ago
1233
The 3 slashes (///) just looks bloody aweful! Much better to have
/*md
* ...
*/
Agree, that actually looks better and needs ni explanation.
Or maybe with three stars /*** Markdown JavaDoc Comment */ would be better
While I agree that "///" is ugly, I expect anything that starts with "/*" was out of the question because it could kick in unintentionally. "///" puts it completely outside the realm of anything that would be recognized by an old compiler.
That's a personal opinion, objectively there is no reason why one it's better than the other.
In the other hand there are other la gushes that already uses /// to specify documentation comments like Dart and C#, so Java it's kinda following a trend
Agree, these javadocs are usually lengthy consisting of many lines. Now, it needs a better IDE support to add those three slashes. Plus this does not look clean imo.
stick with a conversational style.
avoid sounding like a marketeer or academic.
use words, you'd say when talking with developers in-person, one-on-one.
no one says "moreover" in normal conversation.
Well, I also use "moreover" a lot and yet, I'm not a native speaker 😉
@@delabassee You use "moreover" in casual conversation ?
If yes, I'd be interested to hear some examples.
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
Great, I can't wait to have a big wall of nonsense text that has nothing to do with what it's describing.
AI is a companion tool, not a substitute
@@CraccaHacka it what is going on - young generation of developers uses ChatGPT for to generate a code. Why do you think they would use it to generate documentation? Even Jetbrains promotes own AI for documentation generation
@@yatsuk I know, and it's very sad. In all my attempts at using ChatGPT to generate code, it failed. I guess it's ok for trivial tasks, but it's quite useless for real projects, at least that's my experience.
As for the documentation, again, it may be fine for trivial functions, but it cannot detail the internals, the decisions and “backstory” of more complex ones.
Jetbrains is doing quite bad lately, I disabled all their AI stuff because it just clutters the IDE, plus the new 2024 version is insanely heavy on CPU for some reason
@@CraccaHackaperhaps language models will be instead used to highlight out of date and incorrect documentation
Whatever ChatGPT can generate must not be generated. It can generate what is in the code already. JavaDoc should describe what is NOT in the code.
JAVA still havent figured out how to create good documentation, even after 25 years...disappointing..😢
You speak too fast, this video is difficult to follow. Maybe someone else should do a better job at presenting this content.
Lol I watched it on 2x speed