Subject: Re: bug#50041: Add font-lock-doc-markup-face

From: Mattias Engdegård <[email-masked]>
Date: Fri, 13 Aug 2021 16:34:25 +0200

13 aug. 2021 kl. 16.12 skrev Eli Zaretskii <[email-masked]>:

> Could you show a couple of examples of
> use of this face, and tell how these use cases are handled without
> that face?

Sure! Here is a Java doc comment:

/**
* Wag the dog.
* @return <code>true</code> iff the dog was already wagged.
*/

Here, it would be reasonable to set @return, <code> and </code> in font-lock-doc-markup-face since these are markup elements; the rest of the comment would be in font-lock-doc-face. And indeed, this is precisely what java-mode does today given the new face. 

Without the face it uses font-lock-constant-face which is not necessarily a good choice. The new face enables users and theme authors to select the markup element appearance independently for a good fit with the doc face, and have it work automatically with all language modes that make use of the new face.