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

[Jonathan Gibbons]

On Fri, 19 Jan 2024 16:59:04 GMT, Pavel Rappo <prappo 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.

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

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