[HN Gopher] On Markdown in Java documentation comments
___________________________________________________________________
On Markdown in Java documentation comments
Author : mfiguiere
Score : 150 points
Date : 2023-01-24 16:15 UTC (6 hours ago)
(HTM) web link (mail.openjdk.org)
(TXT) w3m dump (mail.openjdk.org)
| WalterBright wrote:
| 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 wrote:
| Why were you against it?
| mcculley wrote:
| 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.
| hprotagonist wrote:
| there's still at least four marksdown that i can think of
| offhand, and likely far more.
| Decabytes wrote:
| > 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
| zdw wrote:
| 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.
| grumpyprole wrote:
| Is there a formal spec for ReStructuredText? Not every
| project would want a dependency on the Python ecosystem.
| partdavid wrote:
| On the whole, rST for sure has the right stuff. Having a
| document model and a nice standard extensible mechanism for
| syntax really helps. It's been my favorite.
|
| But even when writing my last paper I used Markdown (+pandoc)
| because I had a coauthor and Github et al. have made it more
| familiar to so many more people. Maybe in niches like the
| Python community but it's a distinctly minority option, at
| least where I've worked.
| thangalin wrote:
| > it just falls down.
|
| Oh? These are written in Markdown and typeset using ConTeXt:
|
| * https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software
| _... (see 9.9.1)
|
| * https://www.docdroid.net/eGHQ6O7/autonoma-pdf (see emojis
| and speech bubbles in chapter 2)
|
| * https://impacts.to/downloads/lowres/impacts.pdf (99% pure
| Markdown)
|
| * https://dave.autonoma.ca/blog/2020/04/28/typesetting-
| markdow... (technically XHTML, but can be converted)
| the_af wrote:
| 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 wrote:
| He didn't like when CommonMark was named "Standard Markdown"
| or when it was renamed "Common Markdown:"
|
| https://blog.codinghorror.com/standard-markdown-is-now-
| commo...
|
| 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 wrote:
| Yes, that's the conversation I meant.
|
| Gruber got irritated by even attempting to get his opinion
| on this effort. Very, very weird.
| shp0ngle wrote:
| 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.
| laurent123456 wrote:
| I'm getting a sense that it's standardising around CommonMark.
| xiaq wrote:
| 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.
| prpl wrote:
| 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 wrote:
| 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.
| madduci wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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.
| aarroyoc wrote:
| 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/
| vbezhenar wrote:
| 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.
| jeroenhd wrote:
| 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 wrote:
| ..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 wrote:
| 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.
| NovaX wrote:
| 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
| layer8 wrote:
| I usually use the rendered view because that's just Ctrl+Space
| in my IDE.
| taftster wrote:
| 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.
| bluejekyll wrote:
| 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.
| sodapopcan wrote:
| Elixir has always done this and would well recommend it.
| Godspeed, hope it goes through!
| elijahmoses wrote:
| 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?
| pgwhalen wrote:
| 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 wrote:
| 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.
| brabel wrote:
| 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.
| finnh wrote:
| 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 wrote:
| 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 wrote:
| > 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 </>/&.
| apnew wrote:
| Personally, I think this would be fantastic.
| jillesvangurp wrote:
| 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 wrote:
| @return and @param have always been optional in Javadoc, but
| many do, indeed, force themselves to use them unnecessarily.
___________________________________________________________________
(page generated 2023-01-24 23:00 UTC)