On Markdown in Java documentation comments

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 ]