Subject: bug#72814: 31.0.50; Add a variable controlling doxygen support in C/C++/Java?

From: Vincenzo Pupillo <[email-masked]>
Date: Mon, 09 Sep 2024 11:50:59 +0200

In data martedì 27 agosto 2024 14:22:16 CEST, Eli Zaretskii ha scritto:
> > From: Yuan Fu <[email-masked]>
> > Date: Mon, 26 Aug 2024 20:13:52 -0700
> > Cc: [email-masked],
> > 
> >  [email-masked]
> > 
> > Yuan Fu <[email-masked]> writes:
> > > X-Debbugs-CC: [email-masked] <mailto:[email-masked]>,
> > > [email-masked]
> > > 
> > > Should we add a custom option that controls whether to enable doxygen
> > > support in c-ts-mode/c++-ts-mode/java-ts-mode?
> > > 
> > > Technically this isn’t a problem, since the doxygen support is only
> > > enabled if there’s doxygen grammar on the system. But many people
> > > (me) might install a grammar bundle that includes dozens of
> > > grammars for convenience. Then the doxygen support would turn on when
> > > the user doesn’t really intend to use it.
> > > 
> > > I propose we add custom options like c-ts-mode-enable-doxygen and set it
> > > to t by default, so the default behavior is still to enable doxygen
> > > support when the grammar for it exists, but people who don’t want to pay
> > > for it can turn it off by setting the option to nil.
> > > 
> > > Yuan
> > 
> > Eli, WDYT?
> 
> I'm okay with such an option, but it should be careful to check
> whether the corresponding grammar library is available, and offer a
> user-friendly diagnostic if not.

Try to take a look at this patch. Is it okay?

Vincenzo
>From 0a6d90f25dfddc1da88b5e47a97bc09fe50a6d34 Mon Sep 17 00:00:00 2001
From: Vincenzo Pupillo <[email-masked]>
Date: Mon, 9 Sep 2024 09:20:42 +0200
Subject: [PATCH] Add a user option to disable Doxygen syntax highlighting
 (bug#72814).

Both 'c-ts-mode' and 'java-ts-mode' have a new user option,
'c-ts-mode-enable-doxygen' and 'java-ts-mode-enable-doxygen'
(defaults to t) which allow to disable syntax highlighting of comment
blocks based on the Doxygen grammar.

* lisp/progmodes/c-ts-mode.el: Add the 'c-ts-mode-enable-doxygen' user
option variable to disable doxygen grammar. (bug#72814)

* lisp/progmodes/c-ts-mode.el (c-ts-mode, c++-ts-mode): Use the new
'c-ts-mode-enable-dodygen' option.

* lisp/progmodes/java-ts-mode.el: Add the 'java-ts-mode-enable-doxygen'
user option variable to disable doxygen grammar. (bug#72814)

* lisp/progmodes/java-ts-mode.el (java-ts-mode): Use the new
'java-ts-mode-enable-dodygen' option.

* etc/NEWS: Document the change.
---
 etc/NEWS                       | 16 ++++++++
 lisp/progmodes/c-ts-mode.el    | 71 ++++++++++++++++++++--------------
 lisp/progmodes/java-ts-mode.el | 35 +++++++++++------
 3 files changed, 83 insertions(+), 39 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index c6f8b0062e4..5762bc22c54 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -224,6 +224,22 @@ package of the current buffer.  It is bound to 'C-c C-t p' in 'go-ts-mode'.
 The 'go-ts-mode-build-tags' user option is available to set a list of
 build tags for the test commands.
 
+** C-ts mode
+
++++
+*** New user option 'c-ts-mode-enable-doxygen'.
+By default, 'c-ts-mode-enable-doxygen' is t, and doxygen comment blocks
+are syntax-highlighted if the doxygen grammar is available.  If Non-nil,
+the comment blocks are highlighted like other comments.
+
+** Java-ts mode
+
++++
+*** New user option 'java-ts-mode-enable-doxygen'.
+By default, 'java-ts-mode-enable-doxygen' is t, and doxygen comment blocks
+are syntax-highlighted if the doxygen grammar is available.  If Non-nil,
+the comment blocks are highlighted like other comments.
+
 ** Emacs Lisp mode
 
 ---
diff --git a/lisp/progmodes/c-ts-mode.el b/lisp/progmodes/c-ts-mode.el
index 7f23b30a88a..3adf5673e67 100644
--- a/lisp/progmodes/c-ts-mode.el
+++ b/lisp/progmodes/c-ts-mode.el
@@ -216,6 +216,17 @@ c-ts-mode-emacs-sources-support
   :safe 'booleanp
   :group 'c)
 
+(defcustom c-ts-mode-enable-doxygen t
+  "Enable doxygen syntax highlighting.
+If nil, disable doxygen based font lock for comment.
+This needs to be set before enabling `c-ts-mode'; if you change
+the value after enabling `c-ts-mode', toggle the mode off and on
+again."
+  :version "31.1"
+  :type 'boolean
+  :safe 'booleanp
+  :group 'c)
+
 ;;; Syntax table
 
 (defvar c-ts-mode--syntax-table
@@ -1354,20 +1365,22 @@ c-ts-mode
         (treesit-font-lock-recompute-features '(emacs-devel)))
 
       ;; Inject doxygen parser for comment.
-      (when (treesit-ready-p 'doxygen t)
-        (setq-local treesit-primary-parser primary-parser)
-        (setq-local treesit-font-lock-settings
-                    (append
-                     treesit-font-lock-settings
-                     c-ts-mode-doxygen-comment-font-lock-settings))
-        (setq-local treesit-range-settings
-                    (treesit-range-rules
-                     :embed 'doxygen
-                     :host 'c
-                     :local t
-                     `(((comment) @cap
-                        (:match
-                         ,c-ts-mode--doxygen-comment-regex @cap)))))))))
+      (when c-ts-mode-enable-doxygen
+        (if (not (treesit-ready-p 'doxygen t))
+            (warn "Doxygen language grammar is unavailable, please install it.")
+          (setq-local treesit-primary-parser primary-parser)
+          (setq-local treesit-font-lock-settings
+                      (append
+                       treesit-font-lock-settings
+                       c-ts-mode-doxygen-comment-font-lock-settings))
+          (setq-local treesit-range-settings
+                      (treesit-range-rules
+                       :embed 'doxygen
+                       :host 'c
+                       :local t
+                       `(((comment) @cap
+                          (:match
+                           ,c-ts-mode--doxygen-comment-regex @cap))))))))))
 
 (derived-mode-add-parents 'c-ts-mode '(c-mode))
 
@@ -1415,20 +1428,22 @@ c++-ts-mode
                     #'c-ts-mode--emacs-current-defun-name))
 
       ;; Inject doxygen parser for comment.
-      (when (treesit-ready-p 'doxygen t)
-        (setq-local treesit-primary-parser primary-parser)
-        (setq-local treesit-font-lock-settings
-                    (append
-                     treesit-font-lock-settings
-                     c-ts-mode-doxygen-comment-font-lock-settings))
-        (setq-local treesit-range-settings
-                    (treesit-range-rules
-                     :embed 'doxygen
-                     :host 'cpp
-                     :local t
-                     `(((comment) @cap
-                        (:match
-                         ,c-ts-mode--doxygen-comment-regex @cap)))))))))
+      (when c-ts-mode-enable-doxygen
+        (if (not (treesit-ready-p 'doxygen t))
+            (warn "Doxygen language grammar is unavailable, please install it.")
+          (setq-local treesit-primary-parser primary-parser)
+          (setq-local treesit-font-lock-settings
+                      (append
+                       treesit-font-lock-settings
+                       c-ts-mode-doxygen-comment-font-lock-settings))
+          (setq-local treesit-range-settings
+                      (treesit-range-rules
+                       :embed 'doxygen
+                       :host 'cpp
+                       :local t
+                       `(((comment) @cap
+                          (:match
+                           ,c-ts-mode--doxygen-comment-regex @cap))))))))))
 
 (derived-mode-add-parents 'c++-ts-mode '(c++-mode))
 
diff --git a/lisp/progmodes/java-ts-mode.el b/lisp/progmodes/java-ts-mode.el
index ac104534734..f12c7ec81ef 100644
--- a/lisp/progmodes/java-ts-mode.el
+++ b/lisp/progmodes/java-ts-mode.el
@@ -48,6 +48,17 @@ java-ts-mode-indent-offset
   :safe 'integerp
   :group 'java)
 
+(defcustom java-ts-mode-enable-doxygen t
+  "Enable doxygen syntax highlighting.
+If nil, disable doxygen based font lock for comment.
+This needs to be set before enabling `java-ts-mode'; if you change
+the value after enabling `java-ts-mode', toggle the mode off and on
+again."
+  :version "31.1"
+  :type 'boolean
+  :safe 'booleanp
+  :group 'java)
+
 (defvar java-ts-mode--syntax-table
   (let ((table (make-syntax-table)))
     ;; Taken from the cc-langs version
@@ -401,17 +412,19 @@ java-ts-mode
                 java-ts-mode--font-lock-settings)
 
     ;; Inject doxygen parser for comment.
-    (when (treesit-ready-p 'doxygen t)
-      (setq-local treesit-primary-parser primary-parser)
-      (setq-local treesit-font-lock-settings
-                  (append treesit-font-lock-settings
-                          c-ts-mode-doxygen-comment-font-lock-settings))
-      (setq-local treesit-range-settings
-                  (treesit-range-rules
-                   :embed 'doxygen
-                   :host 'java
-                   :local t
-                   `(((block_comment) @cap (:match "/\\*\\*" @cap)))))))
+    (when java-ts-mode-enable-doxygen
+      (if (not (treesit-ready-p 'doxygen t))
+          (warn "Doxygen language grammar is unavailable, please install it.")
+        (setq-local treesit-primary-parser primary-parser)
+        (setq-local treesit-font-lock-settings
+                    (append treesit-font-lock-settings
+                            c-ts-mode-doxygen-comment-font-lock-settings))
+        (setq-local treesit-range-settings
+                    (treesit-range-rules
+                     :embed 'doxygen
+                     :host 'java
+                     :local t
+                     `(((block_comment) @cap (:match "/\\*\\*" @cap))))))))
 
   (setq-local treesit-font-lock-feature-list java-ts-mode--feature-list)
 
-- 
2.46.0