Support Markdown in javadoc Comments

[Jonathan Gibbons]

Earlier this year, we previewed some work to support being able to use 
Markdown syntax in javadoc comments.

Based on the feedback we received at that time, we withdrew the work, in 
order to come up with a revised proposal [1].

While the JEP gives full details on the latest proposal, below there is 
a summary of the major new features:

-- Jon

[1]: https://openjdk.org/jeps/8316039

-----

# Changes to the Proposed Support for Markdown in Documentation Comments

## New Form for Documentation Comments

A new form of documentation comment is introduced to indicate the use of 
Markdown
in the documentation comment.

The new form is a sequence of adjacent lines each beginning with `///` after
any initial optional whitespace.

For example,

     /// Hello Markdown!
     /// This is a _Markdown_ *comment*.
     public class Demo { }


The use of `///` means that there are no restrictions in the characters that
appear on each line after the `///`. Thus, `*/` may appear in the 
documentation
comment, and there are no problems using `*` as a Markdown list marker.

Incidental leading white appearing immediately after the `///` in each line
of the comment is removed, so that it does not otherwise affect Markdown's
use of leading horizontal whitespace.


## Code Spans and Code Blocks

JavaDoc tags are not recognized within Markdown code spans and code blocks,
and so there is no need to escape use of the `@` character or `{@` sequence
in Markdown code spans and code blocks.

For example,

     /// This code block contains an annotation, not a JavaDoc tag
     ///
     /// ```
     /// @Override
     /// public void m() { }
     /// ```


## Reference Links

The handling of Markdown reference links is extended, such that if a 
reference
is undefined within the comment and matches the syntax for a reference 
to a program
element, then the link will be handled as if it were a JavaDoc `{@link 
...}` or
`{@linkplain ...}` tag, depending on whether the link text is 
effectively the
same as the  link target. Collapsed and shortcut reference links are 
implicitly also supported.

For example,

     /// This is a code link to [java.io.File].
     /// This is a plain link, for determining a 
[random][Random.nextInt()] number.


## Tables

Support for simple tables is provided, using the syntax defined in
Github-flavored Markdown.

For example,

     /// | Latin | Greek |
     /// |-------|-------|
     /// | a     | alpha |
     /// | b     | beta  |
     /// | c     | gamma |


## JavaDoc Tags

JavaDoc tags, both inline tags and block tags, are still supported, although
most uses of inline tags now have a direct Markdown replacement.

For example, in the OpenJDK code base, over 95% of the uses of Javadoc 
inline
tags are for `{@code ...}`, `{@link ...}`, and `{@linkplain ..}`, all of 
which
are now supported by Markdown equivalents. (The next most common tag is
`{@inheritDoc}`, which does not have any natural Markdown equivalent.)


## Other Files

Documentation files (provided in `doc-files` subdirectories), and the 
`overview` file
(specified by the `-overview` option), may now be Markdown files.