I like this idea. I never use rendered docs, I always see them from the source code. And HTML markup adds too much noise. Markdown should be good replacement.

They should look at how Dokka does this for Kotlin. It's kind of builds on the same conventions and syntax and plugs into the same infrastructure for deploying documentation along with jar files (i.e. maven). So it use the same @return, @param and so on tags and a few Kotlin specific ones.

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.

We use a markdown plugin/doclet tool to process javadoc in our codebase, and it's worked wonderfully for many years now.

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

I believe asciidoc would be a better fit for it, especially because there are already tools/plugins for java for generating documentation, so the wheel must not be (once again) reinvented

On Scryer Prolog, after evaluating Markdown, we end up using Djot[0] as it is more predictable and standard than Markdown, while being also very readable.

[0]: https://djot.net/

Is there a canonical Markdown specification now? A machine readable grammar? Last I looked, Markdown was a bunch of almost-compatible interpretations based on lore and opinion.

We've been supporting Markdown in D's documentation comments for a while now. I was initially against it, but I was wrong. It's a welcome feature.

For writing lists, this is going to be a real godsend! I'm really happy to hear this is being considered for first class support. It's hard to understate the value of making lists in documentation easier to both read & write

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?

Personally, I think this would be fantastic.

I can see the advantages of this feature, but like all things, it will take a while for people to become used to it.

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?

Hopefully there’s some overlap with MyST - the markdown format from sphinx. That format is mostly reasonable in terms of extending markdown by enabling sphinx/reST directives.

Isn't this properly called "Common Markdown"? https://blog.codinghorror.com/standard-markdown-is-now-commo...

Maybe some of the issues could be addressed by using another tool like AsciiDoc (or subset from it) or reStructuredText. Another approach could be to define a strict and slightly extended Markdown dialect (everyone is doing it, anyway ...).

As a long time Java who embraced Rust a while ago, this is one thing that I love about Rust. Markdown is fantastic in this situation, it’s as readable in code as it is in the rendered html (or whatever) presentation format.

I like how Flutter does their documentation. It is a base of Markdown but with added features to have videos and templates for repeating text.

Elixir has always done this and would well recommend it. Godspeed, hope it goes through!

Yea, let’s use an weak and undisciplined markup language in a powerful and highly disciplined programming language ‘cause a few HTML tags is too much.