vbezhenar 8 months ago

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

  • jeroenhd 8 months 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 8 months 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.

      • NovaX 8 months 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

        [2] https://github.com/Abnaxos/markdown-doclet

      • rhdunn 8 months 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 8 months 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 8 months 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.

    • arp242 8 months ago

      > Markdown is great for plain text but it's not great for this type of content imo.

      What is missing in Markdown?

    • vbezhenar 8 months 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.

  • layer8 8 months ago

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

  • baby 8 months ago

    This is what Rust does, it works great!

jillesvangurp 8 months ago

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.

  • pron 8 months ago

    @return and @param have always been optional in Javadoc, but many do, indeed, force themselves to use them unnecessarily.

finnh 8 months ago

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

  • jonhohle 8 months ago

    Me as well. This is a change that should have come long ago, but it’s good that it’s being investigated.

    It’s been a while since I’ve looked, but last I did the popular build systems were not generating javadoc by default. That leaves the vast majority of doc reading through editors or code browsers. I doubt most Java devs even know that Javadoc is HTML.

    Moving to Markdown kills two birds with one stone and allows fallback to HTML for the complex cases. I would wager >80% of JavaDocs would instantly look better if they just enabled it by default.

  • layer8 8 months ago

    > you have to choose between "readable in my text editor" and "readable in the compiled form"

    Not sure what you mean by that. You mostly get by with a <p> between paragraphs and the occasional <ul><li> or <pre>. And you’ll have the {@…} tags in any case. IDEs usually highlight HTML tags within javadoc differently, which helps readability.

    The one thing that is indeed annoying is the &lt;/&gt;/&amp;.

    • avgcorrection 8 months ago

      > You mostly get by with a <p> between paragraphs and the occasional <ul><li> or <pre>.

      That’s very noisy when the equivalent MD is so lightweight (hyphen for bullet points is as lightweight as it gets).

      > And you’ll have the {@…} tags in any case. IDEs usually highlight HTML tags within javadoc differently, which helps readability.

      The Java response to anything: Well with an IDE…

      • layer8 8 months ago

        It’s not very noisy compared to full-blown XML or JSON. Certainly not unreadable like the parent claimed.

        About IDEs, yeah, Java is certainly an IDE language, no sensible way around that.

        • avgcorrection 8 months ago

          I’ll give you that. For the people who are writing documentation IN XML OR JSON it’s bound to be a big step up.

madduci 8 months ago

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

  • exabrial 8 months ago

    I think AsciiDoc is a good choice, but it does suffer from the single author ecosystem problem (effectively one maintainer). If the ecosystem were to jump to MarkDown, I have a feeling they'd just make the doc system pluggable eventually and we could sub in AsciiDoc in the future.

    • glmdev 8 months ago

      I also think "adoptability" should be a consideration. Perhaps AsciiDoc would be a slightly better fit, but every developer I know is already familiar with MarkDown and at the end of the day convincing people to write good docblocks is easier if they don't have to pick up new syntax.

      • eadler 8 months ago

        I can't stand both writing and reading markdown and find its use painful. While HTML isn't the nicest at least it has (a) separate markup and content and (b) predictable output.

  • avgcorrection 8 months ago

    Doesn’t AsciiDoc have a problem with nesting elements?

aarroyoc 8 months ago

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/

mcculley 8 months ago

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.

  • Decabytes 8 months ago

    > This has been somewhat ameliorated by the rise of CommonMark, which aims to provide a more formal specification for Markdown, and the adoption of CommonMark (albeit often with some extensions) on some popular social platforms

    They mention CommonMark as a popular specification

  • shp0ngle 8 months ago

    There is CommonMark, but even that is very opiniated.

    One of the issues is that original Markdown used tabs everywhere, but people started using spaces, but some implementations choke down on them.

    The biggest issue in Markdown is that whitespace is significant and important; and there are tons of weird edgecases of all the various rules clashing with each other.

    Even CommonMark has some weird unspecified edgecases.

    I was briefly involved with a Markdown parser implementation… it’s really really hard to parse MarkDown. Not sure if harder than to parse HTML, as I did not do that. But it’s still really really hard.

  • the_af 8 months ago

    What's puzzling is that the creator of Markdown wants it like this, and actively resisted endorsing an official standard. He got into a fight with Jeff Atwood from Coding Horror / StackOverflow because of this.

    • eduction 8 months ago

      He didn’t like when CommonMark was named “Standard Markdown” or when it was renamed “Common Markdown:”


      It also sounds like he ignored an invitation to join the effort to create what became CommonMark.

      Since that was as close as anyone came to standardizing, ya it seems reasonable to conclude he’s fine with the ambiguities.

      • the_af 8 months ago

        Yes, that's the conversation I meant.

        Gruber got irritated by even attempting to get his opinion on this effort. Very, very weird.

      • avgcorrection 8 months ago

        Should have called it Common AppleFan.

  • zdw 8 months ago

    This is the reason that most projects I've been a part of end up on Sphinx/ReStructuredText as the docs generator of choice - has a huge installed base of users and developers spread across many projects.

    Markdown is great for a simple readme, but once you start needing larger more structured docs, or want output formats other than HTML, it just falls down.

  • xiaq 8 months ago

    Much of the community has coalesced around CommonMark.

    You'll still find Markdown implementations with a "don't care" attitude, but if an implementation targets any specification at all it's going to be CommonMark, a superset of it, or (more rarely) a subset of it.

  • hprotagonist 8 months ago

    there's still at least four marksdown that i can think of offhand, and likely far more.

  • laurent123456 8 months ago

    I'm getting a sense that it's standardising around CommonMark.

WalterBright 8 months ago

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.

  • felipelalli 8 months ago

    Why were you against it?

    • WalterBright 8 months ago

      I didn't think it was particularly better than the existing Ddoc primitives.

seadan83 8 months ago

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?

  • seadan83 8 months ago

    Reply/edit. I realize actually.. cdata might be only for XML. Being able to put raw XML examples without everything being escaped is really quite major.

apnew 8 months ago

Personally, I think this would be fantastic.

elijahmoses 8 months ago

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?

  • brabel 8 months ago

    Java almost never removes a feature, specially not one so widespread, there's millions of Javadocs out there based on HTML. I expect they will let you choose forever... having two ways of doing something so basic is probably going to be more annoying than just dealing with the extremely small inconvenience of writing a little HTML.

    • seadan83 8 months ago

      Sounds more like HTML by default and markdown as opt-in. I wouldn't assume it's going to be a required flag when generating javadoc for what the input format is. Perhaps the javadoc generator could even become smart enough to detect which one is being used.

  • pgwhalen 8 months ago

    There is zero chance that HTML JavaDoc will be removed (or even made the default) anytime soon. That would be far too large a change for the Java ecosystem, for an already very conservative language with respect to change.

  • Alupis 8 months ago

    One of the advantages of a constrained systems such as javadoc is it's uniformity and consistency.

    No matter what library, program, codebase I read, if it's Java, I know how to effectively navigate the javadoc documentation. The defaults are good enough most of the time, even without additional developer elaboration/explanations.

    There are still modern languages today that don't do automatic documentation anywhere near as good as javadoc.

    If something like Markdown can be added in addition to the existing javadoc, and coexist and be used intertwined within the same documents - then this will be a huge winner.

prpl 8 months ago

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.

  • zdw 8 months ago

    The MyST flavor of markdown is not the same as GitHub flavor, especially about embedding highlighted/replaced content.

    If you want an example of this breakage, try embedding a Mermaid format diagram in both of them.

    • prpl 8 months ago

      I’m well aware. It’s also a one line change to the myst parser to make that work.

      In any case, it’s because a myst code block with curly brackets is really a sphinx directive.

      That said, they should support the non-directive version, similar to GFM, but would need to embed it. Compared to GFM, though, a plug-in can be added to support plantUML and there’s even crusty ones for graphviz.

      GFM version is also not particularly flexible for large diagrams

cryptos 8 months ago

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

bluejekyll 8 months ago

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.

0235005 8 months ago

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.

sodapopcan 8 months ago

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

andrewgilmartin 8 months ago

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.