4 ms·

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.

taftster 4y ago
Agreed. While I read javadoc for the core SDK and other common libraries, it's very rare that I need to read it for my own (or company's) repositories. Instead, I'm just reading the source code and the javadoc embedded in each source file. 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.
layer8 4y ago
I usually use the rendered view because that’s just Ctrl+Space in my IDE.
jeroenhd 4y ago
In my preferred IDE (IntelliJ) you can enable rendered documentation view which will take the source code comments and render them through some kind of limited HTML renderer. 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.
- usrusr 4y ago
  ..and that preview renderer is presenting markdown just fine when the language doesn't happen to be java. 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.
  - rhdunn 4y ago
    With the evolution of any languages you get cross-pollination between them, be it lambda functions, var/val, Markdown comments, value classes, .... For example, Java borrowed generics from languages like C++, and C# borrowed them from C++ and Java.
    - kmonsen 4y ago
      Is this true? I don't think it is. Generics is very different in all three and c++ and java has sort of the opposite implementation of generics.
      - rhdunn 4y ago
        All 3 use the `Class<T>` syntax and have the ability to create functions that operate on any type. If they weren't influenced by each other (e.g. C++ allows you to specify a template/generic type for a function) they would have different syntax. 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.
  - NovaX 4y ago
    Support for Markdown-based JavaDoc has been available since at least 2009 via multiple implementations [1, 2]. There have been many extensions thanks to the doclets api. The difference here is that Markdown will be included in the standard doclet and supported by the Java team instead of a 3rd party. Kotlin has few innovations and is rarely a source of inspiration for Java changes, e.g. Jetbrain's often called Scala a research language that they borrowed heavily from to design an industry language. [1] https://code.google.com/archive/p/markdown-doclet https://code.google.com/archive/p/markdown-doclet [2] https://github.com/Abnaxos/markdown-doclet https://github.com/Abnaxos/markdown-doclet
- arp242 4y ago
  > Markdown is great for plain text but it's not great for this type of content imo. What is missing in Markdown?
- vbezhenar 4y ago
  I tried this feature and it's extremely ugly. May be I'm getting old but I don't like all new Idea features. AI completion? Bad. Parameter hints? Bad. Rendered javadocs? Bad. I switched to VSCode for all but Java projects. It's not as good but least I don't have to spend time turning off all new features every patch. And Idea getting worse with every patch. Right now I can't use Idea for JS because it refuses to turn off parameter hints and I refuse to use it with parameter hints turned on. 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.
  - beezlewax 4y ago
    Can't you remove those hints in settings? https://stackoverflow.com/questions/48123237/remove-parameter-hints-box-in-visual-studio-code https://stackoverflow.com/questions/48123237/remove-paramete...
    - vbezhenar 4y ago
      For Java I do. For JavaScript, as I said, it does not work because of bug or whatever. It worked for some time at previous version and stopped to work after upgrade. At this point I don't bother anymore and just use VScode for anything except Java.
baby 4y ago
This is what Rust does, it works great!

taftster 4y ago

Agreed. While I read javadoc for the core SDK and other common libraries, it's very rare that I need to read it for my own (or company's) repositories. Instead, I'm just reading the source code and the javadoc embedded in each source file. 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.

layer8 4y ago

I usually use the rendered view because that’s just Ctrl+Space in my IDE.

jeroenhd 4y ago

In my preferred IDE (IntelliJ) you can enable rendered documentation view which will take the source code comments and render them through some kind of limited HTML renderer. 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.

usrusr 4y ago
..and that preview renderer is presenting markdown just fine when the language doesn't happen to be java. 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.
- rhdunn 4y ago
  With the evolution of any languages you get cross-pollination between them, be it lambda functions, var/val, Markdown comments, value classes, .... For example, Java borrowed generics from languages like C++, and C# borrowed them from C++ and Java.
  - kmonsen 4y ago
    Is this true? I don't think it is. Generics is very different in all three and c++ and java has sort of the opposite implementation of generics.
    - rhdunn 4y ago
      All 3 use the `Class<T>` syntax and have the ability to create functions that operate on any type. If they weren't influenced by each other (e.g. C++ allows you to specify a template/generic type for a function) they would have different syntax. 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.
- NovaX 4y ago
  Support for Markdown-based JavaDoc has been available since at least 2009 via multiple implementations [1, 2]. There have been many extensions thanks to the doclets api. The difference here is that Markdown will be included in the standard doclet and supported by the Java team instead of a 3rd party. Kotlin has few innovations and is rarely a source of inspiration for Java changes, e.g. Jetbrain's often called Scala a research language that they borrowed heavily from to design an industry language. [1] https://code.google.com/archive/p/markdown-doclet https://code.google.com/archive/p/markdown-doclet [2] https://github.com/Abnaxos/markdown-doclet https://github.com/Abnaxos/markdown-doclet
arp242 4y ago
> Markdown is great for plain text but it's not great for this type of content imo. What is missing in Markdown?
vbezhenar 4y ago
I tried this feature and it's extremely ugly. May be I'm getting old but I don't like all new Idea features. AI completion? Bad. Parameter hints? Bad. Rendered javadocs? Bad. I switched to VSCode for all but Java projects. It's not as good but least I don't have to spend time turning off all new features every patch. And Idea getting worse with every patch. Right now I can't use Idea for JS because it refuses to turn off parameter hints and I refuse to use it with parameter hints turned on. 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.
- beezlewax 4y ago
  Can't you remove those hints in settings? https://stackoverflow.com/questions/48123237/remove-parameter-hints-box-in-visual-studio-code https://stackoverflow.com/questions/48123237/remove-paramete...
  - vbezhenar 4y ago
    For Java I do. For JavaScript, as I said, it does not work because of bug or whatever. It worked for some time at previous version and stopped to work after upgrade. At this point I don't bother anymore and just use VScode for anything except Java.

baby 4y ago

This is what Rust does, it works great!