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

From: Mattias Engdegård <[email-masked]>
Date: Fri, 13 Aug 2021 19:41:06 +0200

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

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