I can’t wait. As someone spending much of their time in Java I much prefer the idea of markdown to HTML for writing Javadoc.
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.
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.
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).
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.
```java id=example
class HelloWorld {
public static void main(String... args) {
System.out.println("Hello World!"); // @link substring="System.out" target="System#out"
}
}
```
(However, some JS highlighting libraries will strip pre-existing HTML in the code (e.g. PRISM.js [2], as is mentioned in the JEP), negating the @link tag above. Highlight.js [3] seems fine though.)
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).
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...
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.
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.
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.
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.
> 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.
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.
> 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.
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]”
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.
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.
> 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.
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.
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 ...
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.
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.