JEP 467: Markdown Documentation 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

   int count = 0; /** quuxes encountered */

And for inline javadoc in multiline argument lists, which I believe to become ever more common in the postOOP age. These could be implicit @param in the slurp javadoc, just like the markdown lists in the future work part of the JEP (where I to see a real benefit of magic headline/list pairs over repeated @param or @throws):

   void slurp(
      /** quuxes ready to be slurped */ 
     int todo,
      /** quuxes slurped before */ 
     int done
   ) {

(Of course I'm mostly looking at KDoc here, where they already have markdown but where multiline parameter lists are even more common than in current/future java)

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.

Same here. I am so used to

  /**
   *
   */

that I find this visually off-putting. Almost as much the string interpolation in string templates.

  /***

would be much better.

Also /// will be read as a comment with a line starting with a slash until the tooling is updated.

Not yet, but we'd like to have that.

Javadocs are not HTML, it's just a small subset of HTML that's actually supported.

Same here. So pissed that Markdown won the "docs battle". Tables and higher-level semantics in Markdown are a nightmare compared to Asciidoc.

Here.

Did manage to make it work with AsciiDoclet?

Well, you do need things like emphasis, lists, headings etc., which aren't typically part of a programming language.

Github Flavored Markdown (GFM) is a superset of commonmark. The differences are indicated in the GFM spec at https://github.github.com/gfm/.

> 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

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 &lt; 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.

What would you use instead of Javadoc if you didn't use Javadoc?

What’s worse?

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.

> 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.

>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.

The compiler doesn’t need a Markdown parser, only the separate javadoc tool does.

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.

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?

Java programmer argues for another level of indirection, using XML. More news at noon.