JEP 467: Markdown Documentation Comments(openjdk.org)
openjdk.org
JEP 467: Markdown Documentation Comments
https://openjdk.org/jeps/467
64 comments
One little syntactic serendipity of /// is that, together with the following space, the prefix is four characters wide rather than three in /** */ with the [Space][Star][Space] line prefix, which has some minor benefits in terms of consistent indentation. (In fact, this is true whether you use tabs or spaces!)
Same. My vote would certainly go to /*** */, and dropping the leading * on the intermediate lines while you're at it. Or go with an alternative like /*# and # on intermediate lines, because the demand for whitespace clarity is certainly bigger in markdown.
I'm very used to consider line and block comments semantically different. To my mind block is javadoc (or for text addressed at the reader that is not meant for tools, in short for prose) whereas // is for killing source lines (and for killing block comments for tools). With the corollary that // would be absent from perfectly clean code, that removal of // is never wrong. In my own projects, I even add an exception mechanism for // that should be kept, they can be marked with ///*why*/, and why should better be good. "why" can be a key further explained in a regular block comment, the idea is that those lines can be cleanly enabled/disabled/removed with regex.
On a very abstract level, I could describe my position as "languages should have multiple forms of comments that have clearly defined semantic differences". I consider this a paradigm change similar to how modern languages have started to declare one style guide the blessed one, even if technically whitespace is just as insignificant as in the old days of "do what you think is best".
What I do miss, from the old doxygen days, is support for trailing comments for when you want to add a few short words to a field without begging for attention too much. Something like
I'm very used to consider line and block comments semantically different. To my mind block is javadoc (or for text addressed at the reader that is not meant for tools, in short for prose) whereas // is for killing source lines (and for killing block comments for tools). With the corollary that // would be absent from perfectly clean code, that removal of // is never wrong. In my own projects, I even add an exception mechanism for // that should be kept, they can be marked with ///*why*/, and why should better be good. "why" can be a key further explained in a regular block comment, the idea is that those lines can be cleanly enabled/disabled/removed with regex.
On a very abstract level, I could describe my position as "languages should have multiple forms of comments that have clearly defined semantic differences". I consider this a paradigm change similar to how modern languages have started to declare one style guide the blessed one, even if technically whitespace is just as insignificant as in the old days of "do what you think is best".
What I do miss, from the old doxygen days, is support for trailing comments for when you want to add a few short words to a field without begging for attention too much. Something like
int count = 0; /** quuxes encountered */
void slurp(
/** quuxes ready to be slurped */
int todo,
/** quuxes slurped before */
int done
) {
Wasn’t there a whole discussion like 5 years ago about deprecating multi-line doc comments (/** */ and /*! */) in Rust, in favor of using /// and //! exclusively, but a blind developer raised a pretty important accessibility issue with that, because their screen reader would always interject “slash slash slash” in the middle of a sentence when they were reading the docs.
I was trying to find the issue in a web search, but failed.
If I remember correctly it was important to keep multi-line doc comments in the language even if they are seldomly used, because it allows developers using assistive technology the possibility to read doc comments uninterrupted.
I was trying to find the issue in a web search, but failed.
If I remember correctly it was important to keep multi-line doc comments in the language even if they are seldomly used, because it allows developers using assistive technology the possibility to read doc comments uninterrupted.
While accessibility is important, /// is used in the .net world, perhaps the screenreader should handle that scenario?
I remember the issue being quite a bit ago, so perhaps the tooling has improved in the meantime (I only use screen readers for testing, not developing, so I wouldn’t know). If not, perhaps Java doing this will be the catalist.
I imagine that it isn’t hard for developers with screen readers to have an editor macro turn /// comments into /** and back in the rust world. But if /// were the only option then there is no such workaround for developers and their only options are to endure or request the improvements (or send a PR if using open source tools).
I imagine that it isn’t hard for developers with screen readers to have an editor macro turn /// comments into /** and back in the rust world. But if /// were the only option then there is no such workaround for developers and their only options are to endure or request the improvements (or send a PR if using open source tools).
Same here. I am so used to
Also /// will be read as a comment with a line starting with a slash until the tooling is updated.
/**
*
*/
/***
Also /// will be read as a comment with a line starting with a slash until the tooling is updated.
Although it is not mentioned in the JEP, I wonder if we can use fenced code blocks as @snippet tags [1]. Of course one can still use {@snippet}, but fenced code blocks seem to me to be the go-to for code quoting in Markdown.
[1] https://openjdk.org/jeps/413 [2] https://prismjs.com/faq.html#if-pre-existing-html-is-strippe... [3] https://jsfiddle.net/LFJKR/
```java id=example
class HelloWorld {
public static void main(String... args) {
System.out.println("Hello World!"); // @link substring="System.out" target="System#out"
}
}
```
[1] https://openjdk.org/jeps/413 [2] https://prismjs.com/faq.html#if-pre-existing-html-is-strippe... [3] https://jsfiddle.net/LFJKR/
Not yet, but we'd like to have that.
Rust has this, it's a great QOL feature, glad to see it spread widely
I used pegdown-doclet for this for a long time. It made documentation in code as easy to read as the generated docs. I don’t think most developers knew that JavaDoc was HTML to begin with (or evernlooked at the rendered docs).
Javadocs are not HTML, it's just a small subset of HTML that's actually supported.
From the JavaDoc docs[0] under the heading “Write comments in HTML”:
> The text must be written in HTML with HTML entities and HTML tags. You can use whichever version of HTML your browser supports.
0 - https://docs.oracle.com/javase/8/docs/technotes/tools/window...
> The text must be written in HTML with HTML entities and HTML tags. You can use whichever version of HTML your browser supports.
0 - https://docs.oracle.com/javase/8/docs/technotes/tools/window...
Ok, I admit I probably read this a long time ago and didn't bother to ever check as I never see anything very advanced in HTML used in Javadocs...
But if you're going to link to the docs, at least link to the modern Java Documentation, not some ancient Java 8 version of the javadoc tool:
https://www.oracle.com/technical-resources/articles/java/jav...
But if you're going to link to the docs, at least link to the modern Java Documentation, not some ancient Java 8 version of the javadoc tool:
https://www.oracle.com/technical-resources/articles/java/jav...
That was the first Oracle link that appeared in search results for me. I think it’s probably more relevant to go backwards however. Javadoc 1.2, for example, has the same quote I originally included - https://web.archive.org/web/20010129031800/http://java.sun.c...
I think I "learned" that from StackOverflow... the top answer does say the same thing I was saying: "Javadoc permits only a subset of HTML tags."
https://stackoverflow.com/questions/16481230/allowed-html-ta...
https://stackoverflow.com/questions/16481230/allowed-html-ta...
You can put arbitrary HTML body content in javadoc. There is no specification that limits it, and the standard doclet just passes it through as-is.
This is similar to HTML in Markdown, incidentally.
This is similar to HTML in Markdown, incidentally.
Who else prefers AsciiDoc syntax?
Here.
Did manage to make it work with AsciiDoclet?
Did manage to make it work with AsciiDoclet?
The worst thing about HTML as docs is that you have to encode your code. You should just be able to write the code for the programming language you are using directly in the docs. Anything else is just nuts.
Well, you do need things like emphasis, lists, headings etc., which aren't typically part of a programming language.
What do you mean? I’m talking about Java code inside javadoc, like code example docs.[1] That’s straightforward if the doc markup is MarkDown with code fences.
The MarkDown code character backtick is especially great for Java since it’s not a metacharacter in the Java syntax.
[1] I didn’t mean writing docs in Java itself, whatever that would look like.
The MarkDown code character backtick is especially great for Java since it’s not a metacharacter in the Java syntax.
[1] I didn’t mean writing docs in Java itself, whatever that would look like.
Oh, ok. Yeah, that's supported, but it's also supported today without HTML with the snippet tag (and @code tag).
Okay great. Thanks Ron :)
I use a very low-tech solution: I stick a <pre> tag at the start of javadoc comments, and make liberal use of empty lines for spacing.
So I don't use any advanced html tags and stuff. Of course I use @link, which is the most useful feature of javadoc.
BTW, maybe the 'meaning' of <style> tags should be clarified for ambitious documenters... It seems they only affect the one javadoc they are inside of, which is pretty useless.
So I don't use any advanced html tags and stuff. Of course I use @link, which is the most useful feature of javadoc.
BTW, maybe the 'meaning' of <style> tags should be clarified for ambitious documenters... It seems they only affect the one javadoc they are inside of, which is pretty useless.
I wish TSDoc would also support this, not to mention get a little love and attention in general. The spec for code linking has never been finished and the tooling like typedoc is limited and cumbersome, not to mention inconsistent with how other tools like VS Code parse and show it.
Golang tried the same thing. The result seems half-hearted but it does work and it's close to "normal" Markdown.
That’s how comments also work in the Dart language and I really like it. Happy to see this change.
How different is the javadoc markdown dialect from that of github?
Github Flavored Markdown (GFM) is a superset of commonmark. The differences are indicated in the GFM spec at https://github.github.com/gfm/.
Extensions aside the major difference is the handling of line breaks: in markdown they get discarded, you need two to separate paragraphs.
In GFM, individual line break are translated to line breaks in the output.
In GFM, individual line break are translated to line breaks in the output.
> Markdown documentation comments are written in the CommonMark variant of Markdown. There are enhancements to links, to allow convenient linking to other program elements. Simple GFM pipe tables are supported, as are all JavaDoc tags.
https://openjdk.org/jeps/467#Syntax
https://openjdk.org/jeps/467#Syntax
Are Javadocs still a thing? When I was young and coded Java the last time that was all fancy and normal to do. But today?
Also wish C# would switch to Markdown comments instead of this XML nonsense. This JEP looks so clean.
Also wish C# would switch to Markdown comments instead of this XML nonsense. This JEP looks so clean.
It absolutely is. Perhaps not so much as in carefully thought out to become the only usage instruction ever needed and manually uploaded to the intranet for your tiny in-house lib, but as in all java tooling knows javadoc, expects its existence and presents it at every opportunity. It's the way to attach some description to a method and doing it any other way is considered wrong. Build plugins (or is it default by now?) pick it up for packaging and distribution through the maven repository hierarchy and when a library ends up in your dependency tree without a javadoc jar you suddenly remember that this is actually possible.
What's dead in many environments is going fancy with the HTML. I think most codebases have nothing or very little in terms of formatting outside the @something keywords. Then the only trace of html is the pain of typing < instead of <. For things like emphasis, chances are people already write it in markdown snytax instead of html even assuming that the markdown will never be read in a formatted way.
What's dead in many environments is going fancy with the HTML. I think most codebases have nothing or very little in terms of formatting outside the @something keywords. Then the only trace of html is the pain of typing < instead of <. For things like emphasis, chances are people already write it in markdown snytax instead of html even assuming that the markdown will never be read in a formatted way.
> Are Javadocs still a thing? When I was young and coded Java the last time that was all fancy and normal to do. But today?
Automated API documentation based on code comments never really died, but the popularity of dynamically typed programming languages had a lot of devs writing API docs separately by hand for a while. Even though some dynamically typed languages had tools for it, they were ignored because nobody had reliable IDE integrations for Javascript/Python, and maybe (?) because of a sentiment that it is a weird enterprise thing to do. Many open source projects adopted casually-written documentation more focused on usage examples, skipping out on detailed documentation of procedures that are deemed too obvious to need docs.
But nowadays we are in a golden age of doc generator tools across various languages.
Automated API documentation based on code comments never really died, but the popularity of dynamically typed programming languages had a lot of devs writing API docs separately by hand for a while. Even though some dynamically typed languages had tools for it, they were ignored because nobody had reliable IDE integrations for Javascript/Python, and maybe (?) because of a sentiment that it is a weird enterprise thing to do. Many open source projects adopted casually-written documentation more focused on usage examples, skipping out on detailed documentation of procedures that are deemed too obvious to need docs.
But nowadays we are in a golden age of doc generator tools across various languages.
What would you use instead of Javadoc if you didn't use Javadoc?
Nice, markdown can help to make java comment easier.
Give it to Java to look at nearly every other language and come up with a strictly worse implementation of a useful feature.
What’s worse?
The requirement to have every line marked as essentially a single line comment, adding a lot of visual noise and basically requiring tool support to automate this tedious work.
Rust (and per another commenter, c#) both use the same styling.
From having done rust development, you get used to it pretty quickly and it becomes no noisier than the repeated stars in the block comments.
I’d prefer just having the comment block start with `/*#` personally since Java already standardized on block style comments but this is hardly “strictly worse [than all other languages]”
From having done rust development, you get used to it pretty quickly and it becomes no noisier than the repeated stars in the block comments.
I’d prefer just having the comment block start with `/*#` personally since Java already standardized on block style comments but this is hardly “strictly worse [than all other languages]”
Rather than visual noise, it makes comments sections immediately recoognizable as such. Think of page-long comments containing code samples. The tool support is trivial, and you can always run a simple regex to fix it up.
Line comments in general have the advantage that they can be trivially nested, and the nesting be immediately recognizable as such. For any new programming language, I would only support line comments, for that reason.
Line comments in general have the advantage that they can be trivially nested, and the nesting be immediately recognizable as such. For any new programming language, I would only support line comments, for that reason.
FWIW IntelliJ optionally renders JavaDoc in-editor, kinda capturing that literate programming vibe. I quite like it.
Here's best quick (am on mobile) example I found:
https://blog.jetbrains.com/idea/2020/03/intellij-idea-2020-1...
Here's best quick (am on mobile) example I found:
https://blog.jetbrains.com/idea/2020/03/intellij-idea-2020-1...
> Rather than visual noise, it makes comments sections immediately recoognizable as such.
As if they weren't recognizable as such before
> The tool support is trivial, and you can always run a simple regex to fix it up.
Why all this when you could avoid it from the start?
> Line comments in general have the advantage that they can be trivially nested, and the nesting be immediately recognizable as such.
Has nothing to do with and is not applicable to comments written in Markdown
As if they weren't recognizable as such before
> The tool support is trivial, and you can always run a simple regex to fix it up.
Why all this when you could avoid it from the start?
> Line comments in general have the advantage that they can be trivially nested, and the nesting be immediately recognizable as such.
Has nothing to do with and is not applicable to comments written in Markdown
I don't see the need for this. Java having a Mardown parser within its compiler just seems wildly out of scope for not a lot of benefit. This seems like the use case of an IDE extension, or a website that host code, not the compiler itself.
The javadoc tool is useful for creating simple HTML documentation directly from the source code. But you end up choosing between making the documentation comments legible as source code or legible as HTML. If HTML javadoc is important to a project, this often means that HTML-in-java-comments will prevail, which in turn means that the developer experience of working on and maintaining those docs is poor. Eclipse and IntelliJ both do good HTML rendering of these comments in mouseover/etc displays, but it is quite annoying to open a file and then need to hover the mouse over the main type just to make the documentation legible.
I'd argue the fact that Java included an html parser to parse and generate JavaDoc as part of the core langue has made it still one of the best languages for finding and reading documentation. Yes, many smaller packages and libraries are just blank auto-generated docs that tell you nothing, but the packages with a well written set of javadocs are wonderful to work with. And a standard with a built in parser means once you know how to read it one place, you know how to read it anywhere. And your IDE will always know how to parse it.
Rust likewise has a standard and parser built in (markdown in this case) and even took it a step further and allowed your example doc code to be runnable and testable.
Personally I've long wanted to see JavaDoc allow markdown. As the JEP examples show, trying to make any javadoc comments that format nicely for the javadoc parsers means making documentation that's hard to read when you're in the code itself. Even the most basic of markdown parsing covers probably 90% of what you'd put in javadoc, and would make reading (and writing) good JavaDoc that much better.
Rust likewise has a standard and parser built in (markdown in this case) and even took it a step further and allowed your example doc code to be runnable and testable.
Personally I've long wanted to see JavaDoc allow markdown. As the JEP examples show, trying to make any javadoc comments that format nicely for the javadoc parsers means making documentation that's hard to read when you're in the code itself. Even the most basic of markdown parsing covers probably 90% of what you'd put in javadoc, and would make reading (and writing) good JavaDoc that much better.
> Java having a Mardown parser within its compiler just seems wildly out of scope for not a lot of benefit.
It won't. The `javadoc` tool parses doc comments and outputs HTML, not `javac`.
> This seems like the use case of an IDE extension, or a website that host code
Disagree. I find often enough that I read Java code in vim or simply using less or cat. Having doc comments that are more readable would be helpful. And it seems silly that every website code hosting solution should have to implement a javadoc parser, when a much simpler solution exists: use markup that is readable as-is.
If you don't want to use this, that's fine; you can continue writing your javadoc comments as you have in the past. That's no reason to suggest that the rest of us should be stuck in the past.
It won't. The `javadoc` tool parses doc comments and outputs HTML, not `javac`.
> This seems like the use case of an IDE extension, or a website that host code
Disagree. I find often enough that I read Java code in vim or simply using less or cat. Having doc comments that are more readable would be helpful. And it seems silly that every website code hosting solution should have to implement a javadoc parser, when a much simpler solution exists: use markup that is readable as-is.
If you don't want to use this, that's fine; you can continue writing your javadoc comments as you have in the past. That's no reason to suggest that the rest of us should be stuck in the past.
>Java having a Mardown parser within its compiler just seems wildly out of scope for not a lot of benefit.
I don't think javac does anything with javadoc or will do anything on this new Markdown doc. It's just comments it will ignore. So nothing should be added to the compiler - it's a separate tool that handles source to javadoc generation.
>This seems like the use case of an IDE extension, or a website that host code, not the compiler itself.
That's how we get complicated setups with external dependencies, 20 non-standard ways to do something, different habbits from project to project and company to company, and a mix of different (new and legacy) versions of those non-standards in any larger codebase.
I don't think javac does anything with javadoc or will do anything on this new Markdown doc. It's just comments it will ignore. So nothing should be added to the compiler - it's a separate tool that handles source to javadoc generation.
>This seems like the use case of an IDE extension, or a website that host code, not the compiler itself.
That's how we get complicated setups with external dependencies, 20 non-standard ways to do something, different habbits from project to project and company to company, and a mix of different (new and legacy) versions of those non-standards in any larger codebase.
[deleted]
The compiler doesn’t need a Markdown parser, only the separate javadoc tool does.
I would argue that API doc text should not be inlined with code at all. It's just noise. It should be in a separate XML file with a minimal schema. Then building the javadoc is just running xsltproc with a javadoc.xslt. Then you also have the option to use your own xslt file to generate pages that integrate with your com / org site (like learn.microsoft.com).
No thank you. As someone who has to read code in addition to writing it, it's great to have the doc comments right there, so I don't have to open and search through another document.
There's also the issue of keeping things up to date: it's much more likely that a programmer is going to keep docs up to date if the doc is right there along with the code than if it's in a separate file.
Not to mention... XML... ugh, no, let's not.
There's also the issue of keeping things up to date: it's much more likely that a programmer is going to keep docs up to date if the doc is right there along with the code than if it's in a separate file.
Not to mention... XML... ugh, no, let's not.
I'm not a fan of XML either with the exception of one purpose which is document processing using XSLT. XSLT is THE correct way to generate documents. Markdown is extremely limited by comparison.
And I'm not suggesting that there would be no documentation in the code. Javadoc is written for consumers of the code being document. That is incorrect. The comments should be optimized for the developers of the code itself. And it should not explain what the code does if you can just read the code itself.
So again, IMO, javadoc is a mistake. It mixes up two largely different things.
Also, when you downvote someone, it's not supposed to be because you don't agree with their view. You downvote someone when they say something that does not contribute to the discussion. But do what you will ...
And I'm not suggesting that there would be no documentation in the code. Javadoc is written for consumers of the code being document. That is incorrect. The comments should be optimized for the developers of the code itself. And it should not explain what the code does if you can just read the code itself.
So again, IMO, javadoc is a mistake. It mixes up two largely different things.
Also, when you downvote someone, it's not supposed to be because you don't agree with their view. You downvote someone when they say something that does not contribute to the discussion. But do what you will ...
Hard disagree. I often read header files directly for documentation and think it’s pretty great. Makes it easy to delve into the source if needed and I dont have to leave my terminal/nvim
You would be wrong. The closer documentation is to the code, the more likely it is to be seen, and to be updated. Reading and writing the docs are more common operations than “writing a new doc transformation tool” by at least 4 or 5 orders of magnitude; the ease of writing new doc transformation tools should not be the determining factor in a design.
It’s much easier to have it inline.
Is there a reason why in addition to being inline it couldn’t also be on its own and off to the side?
Is there a reason why in addition to being inline it couldn’t also be on its own and off to the side?
Java programmer argues for another level of indirection, using XML. More news at noon.
HTML may produce nice output when everything is processed, but inline it’s ugly and distracting. This is exactly the problem Gruber designed markdown to fix.
Personally I’m not big on /// as it’s pretty visually heavy. I understand their reasoning for not allowing it in /** */ blocks. I’d be happy with maybe //** */ or /*** */, but I’m just bike-shedding.
Its a great QOL feature idea and I’ll be happy when I can start using it.