4 ms·

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

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 3y 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.
deleted 3y ago
[deleted]
tpmoney 3y 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.
kelnos 3y 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 3y 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.
layer8 3y ago
The compiler doesn’t need a Markdown parser, only the separate javadoc tool does.

anatnom 3y 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.

deleted 3y ago

[deleted]

tpmoney 3y 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.

kelnos 3y 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 3y 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.

layer8 3y ago

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