On Markdown in Java documentation comments
mail.openjdk.org
mail.openjdk.org
HTML inside of javadoc is very awkward. I hardly ever use it unless I know I'm going to be generating javadoc for a published library. Instead, I'm just already putting markdown-like formatting in the comments already.
I much prefer that to switching to Markdown. Markdown is great for plain text but it's not great for this type of content imo.
At the current trajectory of java making it to hn front page seemingly every day with yet another mosaic piece of trying to become kotlin, we can only hope for jetbrains ownership to not be easily tempted by Oracle dollars.
Java generics ended up the way they did because Java had/has a strong backward compatibility guarantee and wanted to fit into existing List/etc. interfaces and classes that work on objects. This resulted in the decision to erase the type from the runtime bytecode signature.
C# supports reified generics as a result of looking at how Java implemented generics and the problems that introduced. Microsoft were also in a position where .NET/CLR were at version 1, so made the decision to break the bytecode for version 2 in order to support reified generics.
Scala, Kotlin, and other languages have worked to follow the C# model as much as they can within the limitations of the Java bytecode/runtime.
What is missing in Markdown?
I don't even remember last time I liked new Idea feature. They're breaking my workflow with every new release. And I can't stay on old release because I need new Java support which is not backported obviously.
Some differences:
- obviously it supports markdown and does the obvious things with that. Particularly using code blocks for examples is nice.
- you can refer to parameters and other things inline, so you don't have to have a separate line for each parameter or the return value but you can write something like "Returns the square root of [myparam]". No need to spell out @return or @param myparam
- it encourages to write short documentation. You don't have to list each parameter for example. If it is obvious from the signature, it won't force you to spell out that the parameter number is indeed an Int. That's a good thing, a lot of Javadoc is just spelling out things that are obvious and skipping all the not so obvious things.
- it has github markdown as an output options. Nice in combination with a static site generator or github sites.
The fact that whitespace isn't significant in standard javadoc is complete insanity - you have to choose between "readable in my text editor" and "readable in the compiled form", and there's no way to have both. Unless you use a 3rd party thing to accept markdown (or other format with significant whitespace).
It’s been a while since I’ve looked, but last I did the popular build systems were not generating javadoc by default. That leaves the vast majority of doc reading through editors or code browsers. I doubt most Java devs even know that Javadoc is HTML.
Moving to Markdown kills two birds with one stone and allows fallback to HTML for the complex cases. I would wager >80% of JavaDocs would instantly look better if they just enabled it by default.
Not sure what you mean by that. You mostly get by with a <p> between paragraphs and the occasional <ul><li> or <pre>. And you’ll have the {@…} tags in any case. IDEs usually highlight HTML tags within javadoc differently, which helps readability.
The one thing that is indeed annoying is the </>/&.
That’s very noisy when the equivalent MD is so lightweight (hyphen for bullet points is as lightweight as it gets).
> And you’ll have the {@…} tags in any case. IDEs usually highlight HTML tags within javadoc differently, which helps readability.
The Java response to anything: Well with an IDE…
About IDEs, yeah, Java is certainly an IDE language, no sensible way around that.
[0]: https://djot.net/
They mention CommonMark as a popular specification
https://blog.codinghorror.com/standard-markdown-is-now-commo...
It also sounds like he ignored an invitation to join the effort to create what became CommonMark.
Since that was as close as anyone came to standardizing, ya it seems reasonable to conclude he’s fine with the ambiguities.
Gruber got irritated by even attempting to get his opinion on this effort. Very, very weird.
You'll still find Markdown implementations with a "don't care" attitude, but if an implementation targets any specification at all it's going to be CommonMark, a superset of it, or (more rarely) a subset of it.
Markdown is great for a simple readme, but once you start needing larger more structured docs, or want output formats other than HTML, it just falls down.
But even when writing my last paper I used Markdown (+pandoc) because I had a coauthor and Github et al. have made it more familiar to so many more people. Maybe in niches like the Python community but it's a distinctly minority option, at least where I've worked.
Oh? These are written in Markdown and typeset using ConTeXt:
* https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_... (see 9.9.1)
* https://www.docdroid.net/eGHQ6O7/autonoma-pdf (see emojis and speech bubbles in chapter 2)
* https://impacts.to/downloads/lowres/impacts.pdf (99% pure Markdown)
* https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow... (technically XHTML, but can be converted)
One of the issues is that original Markdown used tabs everywhere, but people started using spaces, but some implementations choke down on them.
The biggest issue in Markdown is that whitespace is significant and important; and there are tons of weird edgecases of all the various rules clashing with each other.
Even CommonMark has some weird unspecified edgecases.
I was briefly involved with a Markdown parser implementation… it’s really really hard to parse MarkDown. Not sure if harder than to parse HTML, as I did not do that. But it’s still really really hard.
Second, adding XML snippets* into documentation is going to become far easier with markdown. It's common to want some documentation that says: "add this XML example to your config file: ...{xml}...". Generally at that point the HTML generation is completely thrown out of the window for the sake of the documentation being able to be usable with ready-to-go copy/paste examples. (Grant-it, I've yet to really work on any project that uses generated javadoc documentation. [Which just perhaps shows I have never contributed to any core java libraries or anything meant tob be consumed as a java library]. But for example, my advice to colleagues that I work with for documentation is to focus on audience and to take note that HTML-javadoc is never generated for the project they are working in. So don't optimize for a generator that is never run, optimize readability for the actual dev sitting between their keyboard and chair that is reading the javadoc)
* Yeah, CDATA could be employed, but who wants to do that?
I also see the possibility of some programmers, who will be attached to the old way in which java code documentations is displayed.
Although, I would love to ask, will there be an option to choose, to upgrade or not?
No matter what library, program, codebase I read, if it's Java, I know how to effectively navigate the javadoc documentation. The defaults are good enough most of the time, even without additional developer elaboration/explanations.
There are still modern languages today that don't do automatic documentation anywhere near as good as javadoc.
If something like Markdown can be added in addition to the existing javadoc, and coexist and be used intertwined within the same documents - then this will be a huge winner.
If you want an example of this breakage, try embedding a Mermaid format diagram in both of them.
In any case, it’s because a myst code block with curly brackets is really a sphinx directive.
That said, they should support the non-directive version, similar to GFM, but would need to embed it. Compared to GFM, though, a plug-in can be added to support plantUML and there’s even crusty ones for graphviz.
GFM version is also not particularly flexible for large diagrams