On Markdown in Java documentation comments

Re:On Markdown in Java documentation comments by madduci on Tuesday January 24, 2023 @12:26PM (#34506829)

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

[ Parent | on HN ]

Re:On Markdown in Java documentation comments by exabrial on Tuesday January 24, 2023 @12:38PM (#34507029)

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.

[ Parent | on HN ]

Re:On Markdown in Java documentation comments by glmdev on Tuesday January 24, 2023 @12:56PM (#34507300)

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.

[ Parent | on HN ]

Re:On Markdown in Java documentation comments by eadler on Tuesday January 24, 2023 @01:14PM (#34507548)

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.

[ Parent | on HN ]

Re:On Markdown in Java documentation comments by avgcorrection on Tuesday January 24, 2023 @06:11PM (#34511981)

Doesn’t AsciiDoc have a problem with nesting elements?

[ Parent | on HN ]