GNU bug report logs - #50041
Add font-lock-doc-markup-face

Previous Next

Full log

View this message in rfc822 format

From: Mattias Engdegård <mattiase <at> acm.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: larsi <at> gnus.org, 50041 <at> debbugs.gnu.org
Subject: bug#50041: Add font-lock-doc-markup-face
Date: Fri, 13 Aug 2021 19:41:06 +0200

[Message part 1 (text/plain, inline)]

13 aug. 2021 kl. 17.57 skrev Eli Zaretskii <eliz <at> 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 (application/octet-stream, attachment)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.