RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]

[Pavel Rappo]

On Tue, 30 Jan 2024 00:47:33 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> > Musing on this more.
> > Can/should we, without introducing probably unwelcome `Kind.MD` to `javax.tools.JavaFileObject.Kind`, teach javac to recognise `package.md` similarly to how it recognises legacy `package.html`? If we are aiming for Markdown to be a drop in replacement for traditional javadoc comments, we might want to go the extra mile.
> > I'm pleased to see that Markdown `-overview` files work just fine.
> 
> No. There are times to let go of legacy behavior, and even if this is not the time to remove support for `package.html`, there is no reason to go backwards and support `package.md`. The preferred replacement for `package.html` has long been `package-info.java` and you can put Markdown content in that file with no issues.
> 
> In similar fashion, remember the recent discussion as to whether we should support `@deprecated` in Markdown comments as marking the declaration as _deprecated_, even without the `@Deprecated` annotation. The general consensus was to not persist with that legacy behavior.

Okay.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484693923