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

[Mattias Engdegård]

13 aug. 2021 kl. 17.57 skrev Eli Zaretskii <eliz@gnu.org>:

> 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?

Yes.

>  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.

It was assumed that the user of the new face would already be familiar with 
font-lock-doc-face and its uses.
The first version of the patch did mention both Javadoc and Doxygen but I 
re-wrote it after your comments indicated that it might have been unclear. I've 
now put that explanation back and extended the face doc string and manual entry.

>> Without the face it uses font-lock-constant-face
> 
> I'd expect font-lock-comment-face, what am I missing?

`font-lock-comment-face` is used for ordinary comments, not doc comments. The 
language mode uses the standard conventions to decide whether a comment is one 
or the other. To continue with Java as the example,

/* An ordinary comment. */  -- set in font-lock-comment-face
/** A javadoc comment. */   -- set in font-lock-doc-face

java-mode uses font-lock-doc-face for doc comments as intended. It also needs a 
face for doc markup but since there is none it repurposes 
font-lock-constant-face for that. See cc-fonts.el.

You can try this yourself in a buffer with java-mode.

0001-Add-font-lock-doc-markup-face-bug-50041.patch
Description: Binary data