On Markdown in (Java) documentation feedback…

Jonathan Gibbons
jonathan.gibbons at oracle.com

Mon Jan 23 18:21:11 UTC 2023

As some folks have already observed, we're investigating the potential of
supporting Markdown in Java documentation feedback.

Why are we doing this?  It has been an off-the-cuff request for some time now, since
the emergence of Markdown as a well-liked authoring format, and so  we're doing it
for all the identical causes that authors choose to make use of Markdown  as an alternative of uncooked
HTML in standalone documentation. Specifically, utilizing uncooked HTML is considerably
clunky and visually intrusive, for easy formatting duties, like font modifications,
lists, and tables, which might be usually desired in API documentation.

What challenges must be addressed?  There are two major challenges to be
addressed: which model of Markdown, and, learn how to incorporate the power to make use of
Markdown in documentation feedback?

 From its starting, Markdown suffered from having tough implementations,
with out a widespread specification, and infrequently with considerably totally different behaviors. The
drawback was exacerbated by the introduction of a number of disparate extensions,
all looking for to offer further performance not supported within the authentic
model. This has been considerably ameliorated by the rise of CommonMark, which
goals to offer a extra formal specification for Markdown, and the adoption of
CommonMark (albeit usually with some extensions) on some fashionable social platforms.

When it comes to utilizing Markdown inside documentation feedback, we don't need to
change the assist for the prevailing performance of inline tags (like`{@hyperlink
...}`) or block tags (like`@param`,`@return`, and`@throws`), most of which do
not have an equal in primary Markdown. (The one apparent tag that does have a
alternative is using back-ticks for a code span as an alternative of`{@code ...}`.)
It will be impractical to switch using all current tags, and the power
to offer user-defined tags, with Markdown extensions, and so we're left with
eager to accommodate using commonplace and user-defined tags alongside
Markdown in documentation feedback. A barely totally different method of claiming that's
that we need to  assist using Markdown constructs in documentation feedback
wherever that uncooked HTML can be utilized in a documentation remark right this moment.

Markdown shouldn't be HTML. Whereas it does accommodate using acceptable HTML
components, Markdown interprets some otherwise-plain textual content otherwise.  Most
notable is its interpretation of whitespace characters. Usually, whitespace
shouldn't be important in HTML (besides in`<pre>` components), however in Markdown, a
clean line is interpreted as a paragraph break. This by itself is sufficient to imply
that we can not allow Markdown by default all over the place, for each new and current
documentation feedback.  That means we have to assist each conventional
feedback (that weren't written with Markdown in thoughts), and feedback that use
the power to make use of Markdown.  And in that heterogeneous world, we must be
in a position to generate API documentation from code which will use a combination of remark
codecs. Of be aware is the power for the`{@inheritDoc}` tag to reference textual content
in numerous lessons, which can even be in numerous tasks.  For instance,
a mission offering custom-made collections (for instance, like Guava), might want
to inherit documentation from the core collections lessons in Java SE.

Markdown shouldn't be with out its issues. It adopts an error-free coverage of "if it is
not a sound syntactic assemble, it should be literal textual content". In no instances does it
report errors. If enter seems to be prefer it may be HTML, it's handed by to the
output, the place it might be caught downstream by an HTML validator if it wasn't
really legitimate HTML, and if the creator chooses to run such a device. If the enter
incorporates HTML with a typo (like a lacking quote for an attribute worth),
Markdown will deal with that fragment of the enter as literal textual content, and generate the
acceptable HTML for that literal textual content. In that case, the misguided enter will
_not_ be caught by a downstream HTML validator, and if not caught by
proofreading the output, the misguided enter will make all of it the way in which "in clear"
to the generated output. Given the empirical proof that authors do_not_ proofread their generated documentation, and you've got an elevated threat of
issues within the generated output.

Why that is difficulty of error dealing with no more of a difficulty in different contexts? In
different contexts, Markdown is usually write-once and/or considerably short-lived.
And, there's usually very low latency to "preview" the rendered output,
both with an express "Preview" button, or possibly with a "reside preview" that
updates as you sort.  When you have entry to a Markdown editor with reside preview,
strive typing in a string like`<a href="instance.com">instance</a>` and see the way it
is previewed in its incomplete state after which its closing state. So, whether or not you
are typing in some type of design doc, or a commit message on Github, it's
usually simple to confirm whether or not the rendering is as anticipated. In distinction,
documentation feedback are prone to be long-lived, for so long as the API
itself is maintained, and possibly edited or up to date by totally different authors over
time, utilizing totally different instruments. And working`javadoc` to generate the API
documentation could also be seen as an afterthought, after the work of creating and
debugging the implementation of the underlying API.  It will assist if we might
scale back the latency to view the rendered type of a documentation remark, both
with a "Preview" button, or "reside preview", and whereas which may be out of scope
by way of a mission to outline the power to make use of Markdown, we will not less than
outline the characteristic in a method which will improve the adoption in authoring instruments.

 instruments,`javadoc` shouldn't be the one device to course of documentation
feedback. As properly IDEs and different authoring instruments,`jshell` additionally offers the
means to show documentation feedback. Maybe much more than`javadoc` itself,`jshell` could also be known as upon to show each "conventional" feedback, for
information or libraries that don't use Markdown feedback, or to deal with Markdown
feedback, for information or libraries that do use them. Once more, we have to think about
the wants of and implications for different instruments within the ecosystem  when designing a
new characteristic like assist for Markdown in documentation feedback.

-- Jon
-------------- subsequent half --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/javadoc-dev/attachments/20230123/691b655d/attachment.htm>

More information about the javadoc-dev
mailing list