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

[Eli Zaretskii <eliz@gnu.org>]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Fri, 13 Aug 2021 16:34:25 +0200
> Cc: larsi@gnus.org, 50041@debbugs.gnu.org
> 
> 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. 

So this face is for portions of the buffer that are markup for the
text intended to be extracted into the documentation, like JavaDoc or
Doxygen do?  If so, I think the NEWS entry and the doc string should
say so, at least as an example of the intended usage.  I've read the
doc string you suggested several time, and still couldn't figure out
what the face is for: the description seems too abstract.

> Without the face it uses font-lock-constant-face

I'd expect font-lock-comment-face, what am I missing?

Thanks.