4 ms·

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 signifi

by finnh 4y 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 4y 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 4y 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 </>/&.
- avgcorrection 4y 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 4y 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 4y 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.
hacker_junky 4y ago
That's really interesting.

by finnh 4y ago

jonhohle 4y 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 4y 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 </>/&.

avgcorrection 4y 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 4y 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 4y 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.

hacker_junky 4y ago

That's really interesting.