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
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.
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.
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.
Doesn’t AsciiDoc have a problem with nesting elements?