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

[Vincenzo Pupillo <v.pupillo@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1871 bytes --]

In data giovedì 12 settembre 2024 10:31:56 CEST, Eli Zaretskii ha scritto:
> > From: Yuan Fu <casouri@gmail.com>
> > Date: Thu, 12 Sep 2024 00:51:20 -0700
> > Cc: Vincenzo Pupillo <v.pupillo@gmail.com>,
> > 
> >  Bug Report Emacs <bug-gnu-emacs@gnu.org>,
> >  72814@debbugs.gnu.org
> >  
> > > On Sep 11, 2024, at 5:05 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> > >> From: Vincenzo Pupillo <v.pupillo@gmail.com>
> > >> Cc: Bug Report Emacs <bug-gnu-emacs@gnu.org>, 72814@debbugs.gnu.org
> > >> Date: Wed, 11 Sep 2024 11:40:17 +0200
> > >> 
> > >>> Thanks for taking this up! I won’t signal a warning if doxygen grammar
> > >>> isn’t found. Imagine a user without doxygen grammar, and din’t change
> > >>> c-ts-mode-enable-doxygen: they’ll get a warning whenever they open a
> > >>> C file. We should either set c-ts-mode-enable-doxygen to nil by
> > >>> default, or not warn when doxygen grammar doesn’t exist. Otherwise,
> > >>> the patch looks good to me.> >> 
> > >> Okay, fine. But Eli said something different...
> > > 
> > > Not necessarily.  All I said was "issue a user-friendly diagnostic".
> > > We could output the message into *Messages*, and do it only once per
> > > Emacs session.
> > 
> > Another idea: use tertiary value for c-ts-mode-enable-doxygen, t for
> > enable (and issue warning if doxygen isn’t present), nil for enable if
> > doxygen exists but don’t issue any warning, ‘disabled for disable. (I
> > don’t think there’s a convention for the three values of tertiary toggle,
> > is that right Eli?)
> That could also be OK, but I prefer something that does TRT by
> default.

Ciao,
in this new version of the patch, as default, the *-ts-mode-enable-doxygen are 
set to nil, and issue a diagnostic (one per session) when Not-nil and if the  
grammar isn't present. It is OK?

Vincenzo

[-- Attachment #2: 0001-Add-a-user-option-to-enable-Doxygen-syntax-highlight.patch --]
[-- Type: text/x-patch, Size: 6068 bytes --]

From 71de6870d6b341e09fa6c79e38ca73e60fda8805 Mon Sep 17 00:00:00 2001
From: Vincenzo Pupillo <v.pupillo@gmail.com>
Date: Mon, 9 Sep 2024 09:20:42 +0200
Subject: [PATCH] Add a user option to enable 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 nil) which allow to enable 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)
Notifies the user if doxygen grammar is not available.

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

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

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

* etc/NEWS: Document the change.
---
 etc/NEWS                       | 16 ++++++++++++++++
 lisp/progmodes/c-ts-mode.el    | 20 +++++++++++++++++---
 lisp/progmodes/java-ts-mode.el | 18 ++++++++++++++++--
 3 files changed, 49 insertions(+), 5 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index c6f8b0062e4..8de4f886d67 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 nil, and the comment blocks
+are highlighted like other comments.  When Non-nil doxygen comment
+blocks are syntax-highlighted if the doxygen grammar is available.
+
+** Java-ts mode
+
++++
+*** New user option 'java-ts-mode-enable-doxygen'.
+By default, 'java-ts-mode-enable-doxygen' is nil, and the comment blocks
+are highlighted like other comments.  When Non-nil doxygen comment
+blocks are syntax-highlighted if the doxygen grammar is available.
+
 ** Emacs Lisp mode
 
 ---
diff --git a/lisp/progmodes/c-ts-mode.el b/lisp/progmodes/c-ts-mode.el
index 7f23b30a88a..10fa3bc3bb3 100644
--- a/lisp/progmodes/c-ts-mode.el
+++ b/lisp/progmodes/c-ts-mode.el
@@ -65,7 +65,7 @@
 ;; libraries installed.
 ;;
 ;; If the tree-sitter doxygen grammar is available, then the comment
-;; blocks will be highlighted according to this grammar.
+;; blocks can be highlighted according to this grammar.
 
 ;;; Code:
 
@@ -216,6 +216,17 @@ c-ts-mode-emacs-sources-support
   :safe 'booleanp
   :group 'c)
 
+(defcustom c-ts-mode-enable-doxygen nil
+  "Enable doxygen syntax highlighting.
+If Non-nil, enable doxygen based font lock for comment blocks.
+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,7 +1365,7 @@ c-ts-mode
         (treesit-font-lock-recompute-features '(emacs-devel)))
 
       ;; Inject doxygen parser for comment.
-      (when (treesit-ready-p 'doxygen t)
+      (when (and c-ts-mode-enable-doxygen (treesit-ready-p 'doxygen t))
         (setq-local treesit-primary-parser primary-parser)
         (setq-local treesit-font-lock-settings
                     (append
@@ -1415,7 +1426,7 @@ c++-ts-mode
                     #'c-ts-mode--emacs-current-defun-name))
 
       ;; Inject doxygen parser for comment.
-      (when (treesit-ready-p 'doxygen t)
+      (when (and c-ts-mode-enable-doxygen (treesit-ready-p 'doxygen t))
         (setq-local treesit-primary-parser primary-parser)
         (setq-local treesit-font-lock-settings
                     (append
@@ -1527,6 +1538,9 @@ c-or-c++-ts-mode
            (treesit-ready-p 'c))
   (add-to-list 'major-mode-remap-defaults '(c-or-c++-mode . c-or-c++-ts-mode)))
 
+(when (and c-ts-mode-enable-doxygen (not (treesit-ready-p 'doxygen t)))
+  (message "Doxygen syntax highlighting can't be enabled, please install the language grammar."))
+
 (provide 'c-ts-mode)
 (provide 'c++-ts-mode)
 
diff --git a/lisp/progmodes/java-ts-mode.el b/lisp/progmodes/java-ts-mode.el
index ac104534734..177f914160c 100644
--- a/lisp/progmodes/java-ts-mode.el
+++ b/lisp/progmodes/java-ts-mode.el
@@ -25,7 +25,7 @@
 ;;; Commentary:
 ;;
 ;; If the tree-sitter doxygen grammar is available, then the comment
-;; blocks will be highlighted according to this grammar.
+;; blocks can be highlighted according to this grammar.
 
 ;;; Code:
 
@@ -48,6 +48,17 @@ java-ts-mode-indent-offset
   :safe 'integerp
   :group 'java)
 
+(defcustom java-ts-mode-enable-doxygen nil
+  "Enable doxygen syntax highlighting.
+If Non-nil, enable doxygen based font lock for comment blocks.
+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,7 +412,7 @@ java-ts-mode
                 java-ts-mode--font-lock-settings)
 
     ;; Inject doxygen parser for comment.
-    (when (treesit-ready-p 'doxygen t)
+    (when (and java-ts-mode-enable-doxygen (treesit-ready-p 'doxygen t))
       (setq-local treesit-primary-parser primary-parser)
       (setq-local treesit-font-lock-settings
                   (append treesit-font-lock-settings
@@ -428,6 +439,9 @@ java-ts-mode
 (if (treesit-ready-p 'java)
     (add-to-list 'auto-mode-alist '("\\.java\\'" . java-ts-mode)))
 
+(when (and java-ts-mode-enable-doxygen (not (treesit-ready-p 'doxygen t)))
+  (message "Doxygen syntax highlighting can't be enabled, please install the language grammar."))
+
 (provide 'java-ts-mode)
 
 ;;; java-ts-mode.el ends here
-- 
2.46.0