Support Markdown in javadoc Comments

[Victor Nazarov]

Hello Javadoc developers,

below is a slight rephrasing of my comment on reddit. u/pavelrappo asked me
to post it here, so that it can be better discussed.

> Alternate transformers could convert more Markdown constructs to HTML and
JavaDoc tags.
>
> ...
>
> it would be possible to for there to be additional transformers that a
client may choose to use that are adequate and sufficient for their needs.

I feel like it would be better for the JEP to go into some details about
what kind of needs are these.
As a javadoc user, I'm mainly concerned with authoring and consuming
javadoc documentation.
Most of the usage of javadoc tools that I've personally seen was mostly
using default settings.
So for me it is not clear why I would want to convert more Markdown
constructs to HTML and JavaDoc tags? Still it feels like a very important
part of the proposal that can affect other pieces of the design.

Another note is that the problem as stated in the JEP feels like the same
problem [described by Project Babylon](
https://www.youtube.com/watch?v=xbk9_6XA_IY&t=889s), different needs
require different concentrations of syntactic sugar. Low level
optimizations require low level assembly code (for javadoc this is probably
HTML), some require more high-level elements, like javadoc links and some
require full source code like original markdown. So maybe some ideas from
Project Babylon can be borrowed to create a multi-level "Javadoc Model"
that can be used in many different usage scenarios.

--
Victor Nazarov
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/javadoc-dev/attachments/20231013/e32328c9/attachment-0001.htm>