JEP 467: Markdown Documentation Comments

by mfiguiere • 2 years ago

157 62 2 years ago

java-man• 2 years ago

How different is the javadoc markdown dialect from that of github?

wpollock• 2 years ago

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

masklinn• 2 years ago

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.

infogulch• 2 years ago

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

ecshafer• 2 years ago

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.

anatnom• 2 years ago

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.

tpmoney2• 2 years ago

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.

kelnos2• 2 years ago

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.

coldtea• 2 years ago

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.

layer83• 2 years ago

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

marknote• 2 years ago

Nice, markdown can help to make java comment easier.

Georgelemental• 2 years ago

Rust has this, it's a great QOL feature, glad to see it spread widely

bodeadly2• 2 years ago

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

rockwotj• 2 years ago

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

riwsky• 2 years ago

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.

kelnos2• 2 years ago

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.

bodeadly2• 2 years ago

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

j45• 2 years ago

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?

avgcorrection4• 2 years ago

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

MBCook2• 2 years ago

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.

tczMUFlmoNk• 2 years ago

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

frant-hartm• 2 years ago

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.

kaba0• 2 years ago

Just for note, C# also does 3 slashes, so there is prior art.

usrusr2• 2 years ago

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)

runarberg2• 2 years ago

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.

Atotalnoob• 2 years ago

While accessibility is important, /// is used in the .net world, perhaps the screenreader should handle that scenario?

MrBuddyCasino• 2 years ago

Who else prefers AsciiDoc syntax?

splittingTimes• 2 years ago

Here.

Did manage to make it work with AsciiDoclet?

lenkite• 2 years ago

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

troupo4• 2 years ago

For markdown comments though AsciiDoc tables are horrible

jonhohle3• 2 years ago

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

brabel4• 2 years ago

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

layer83• 2 years ago

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.

jonhohle3• 2 years ago

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

gudzpoz• 2 years ago

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

[1] https://openjdk.org/jeps/413 [2] https://prismjs.com/faq.html#if-pre-existing-html-is-strippe... [3] https://jsfiddle.net/LFJKR/

pron3• 2 years ago

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

oaiey• 2 years ago

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.

adrianmsmith• 2 years ago

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

usrusr2• 2 years ago

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.

creatonez• 2 years ago

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.

troupo4• 2 years ago

Give it to Java to look at nearly every other language and come up with a strictly worse implementation of a useful feature.

cowsandmilk• 2 years ago

What’s worse?

troupo4• 2 years ago

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.

avgcorrection4• 2 years ago

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.

pron3• 2 years ago

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

avgcorrection4• 2 years ago

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.

euroderf• 2 years ago

Golang tried the same thing. The result seems half-hearted but it does work and it's close to "normal" Markdown.

bartekpacia• 2 years ago

That’s how comments also work in the Dart language and I really like it. Happy to see this change.

difosfor• 2 years ago

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.

jonasenordin• 2 years ago

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.

JEP 467: Markdown Documentation Comments

Related Stories