From 1bfbb2b706db6a7ca9420b27d22a737deccdd5b0 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Mattias=20Engdeg=C3=A5rd?= <mattiase@acm.org>
Date: Fri, 13 Aug 2021 12:47:39 +0200
Subject: [PATCH] Add font-lock-doc-markup-face (bug#50041)

This face is intended for mark-up syntax and constructs inside text
using font-lock-doc-face; ie, documentation comments and strings in
programming modes.

* lisp/font-lock.el (font-lock-doc-markup-face): New face.
* lisp/cus-theme.el (custom-theme--listed-faces): Add it to the list.
* doc/lispref/modes.texi (Faces for Font Lock): Document it.
* etc/NEWS: Mention it.
---
 doc/lispref/modes.texi | 10 +++++++++-
 etc/NEWS               |  9 +++++++++
 lisp/cus-theme.el      |  2 +-
 lisp/font-lock.el      | 14 +++++++++++++-
 4 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index d48c9cc1af0..4274810cba5 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -3444,9 +3444,17 @@ for string constants.
 
 @item font-lock-doc-face
 @vindex font-lock-doc-face
-for documentation strings in the code.  This inherits, by default, from
+for documentation embedded in program code inside specially-formed
+comments or strings.  This face inherits, by default, from
 @code{font-lock-string-face}.
 
+@item font-lock-doc-markup-face
+@vindex font-lock-doc-markup-face
+for mark-up elements in text using @code{font-lock-doc-face}.
+It is typically used for the mark-up constructs in documentation embedded
+in program code, following conventions such as Haddock, Javadoc or Doxygen.
+This face inherits, by default, from @code{font-lock-constant-face}.
+
 @item font-lock-negation-char-face
 @vindex font-lock-negation-char-face
 for easily-overlooked negation characters.
diff --git a/etc/NEWS b/etc/NEWS
index 19eddb72775..366ea1abd6d 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -149,6 +149,15 @@ invoked with the '--declarations' command-line option.
 ** New command 'font-lock-update', bound to 'C-x x f'.
 This command updates the syntax highlighting in this buffer.
 
++++
+** A new standard face 'font-lock-doc-markup-face'.
+Intended for documentation mark-up syntax and tags inside text that
+uses 'font-lock-doc-face', with which it should harmonise.  It would
+typically be used in structured documentation comments in program
+source code by language-specific modes, for mark-up conventions like
+Haddock, Javadoc or Doxygen.  By default this face inherits from
+'font-lock-constant-face'.
+
 ** The new NonGNU ELPA archive is enabled by default alongside GNU ELPA.
 
 +++
diff --git a/lisp/cus-theme.el b/lisp/cus-theme.el
index f4885d0f52b..7457d9e3236 100644
--- a/lisp/cus-theme.el
+++ b/lisp/cus-theme.el
@@ -66,7 +66,7 @@ Do not call this mode function yourself.  It is meant for internal use."
   shadow secondary-selection trailing-whitespace
   font-lock-builtin-face font-lock-comment-delimiter-face
   font-lock-comment-face font-lock-constant-face
-  font-lock-doc-face font-lock-function-name-face
+  font-lock-doc-face font-lock-doc-markup-face font-lock-function-name-face
   font-lock-keyword-face font-lock-negation-char-face
   font-lock-preprocessor-face font-lock-regexp-grouping-backslash
   font-lock-regexp-grouping-construct font-lock-string-face
diff --git a/lisp/font-lock.el b/lisp/font-lock.el
index 4dc42d9cf6a..c00a62a1607 100644
--- a/lisp/font-lock.el
+++ b/lisp/font-lock.el
@@ -312,6 +312,9 @@ If a number, only buffers greater than this size have fontification messages."
 (defvar font-lock-doc-face		'font-lock-doc-face
   "Face name to use for documentation.")
 
+(defvar font-lock-doc-markup-face       'font-lock-doc-markup-face
+  "Face name to use for documentation mark-up.")
+
 (defvar font-lock-keyword-face		'font-lock-keyword-face
   "Face name to use for keywords.")
 
@@ -2003,7 +2006,16 @@ Sets various variables using `font-lock-defaults' and
 
 (defface font-lock-doc-face
   '((t :inherit font-lock-string-face))
-  "Font Lock mode face used to highlight documentation."
+  "Font Lock mode face used to highlight documentation embedded in program code.
+It is typically used for special documentation comments or strings."
+  :group 'font-lock-faces)
+
+(defface font-lock-doc-markup-face
+  '((t :inherit font-lock-constant-face))
+  "Font Lock mode face used to highlight embedded documentation mark-up.
+It is meant for mark-up elements in text that uses `font-lock-doc-face', such
+as the constructs of Haddock, Javadoc and similar systems."
+  :version "28.1"
   :group 'font-lock-faces)
 
 (defface font-lock-keyword-face
-- 
2.39.5