Support Markdown in javadoc Comments

[Jonathan Gibbons]

On 10/13/23 2:35 AM, Victor Nazarov wrote:
> 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 
> <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


Victor,

Thank you for your interest.

1. Re: additional transformers.

If you are satisfied with the default facilities provided by the javadoc 
tool, then you may not be interested in an ability to extend the 
functionality. Markdown is an imperfectly specified language, and even 
leveraging the CommonMark spec, that is something of a low bar.  Some 
authors may have a compelling desire to use additional well-known 
Markdown constructs -- such as definition lists -- that will not be 
supported out of the box in the work described in the JEP, and others 
may wish to extend the features -- for example, the proposed support for 
tables does not include support for table captions, which may be 
important for authors wishing to generate accessible documentation.

2. Re: "Javadoc Model" and Babylon.

I doubt that (m)any ideas from Project Babylon will apply, although it 
is maybe way too soon to make any reliable prediction. For now, the 
ability to specify alternate transformers should be thought of as just 
an extension point, conceptually similar to doclets and taglets.

-- Jon
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/javadoc-dev/attachments/20231023/96582ab2/attachment.htm>