bug#71550: [PATCH] Add jsdoc support to js-ts-mode

bug#71550: [PATCH] Add jsdoc support to js-ts-mode

[Damien Cassou]

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

Tags: patch

Hi,

jsdoc [1] is a special syntax to document JavaScript code. The attached
patch adds a jsdoc parser and font-lock settings to files using the
`js-ts-mode' major mode if the jsdoc grammar is available. Before/after
screenshots are attached to this email.

[1] jsdoc: https://jsdoc.app/

The new code does *not* make `js-ts-mode' dependent on the availability
of the jsdoc grammar: instead, `js-ts-mode' will keep working as it
works today if the jsdoc grammar is absent.

The support for paragraph filling currently in master is broken because
the prefix '*' isn't added at the beginning of lines when filling
documentation blocks. I tried changing the value of
`c-ts-common--comment-regexp' to include "description" (as this is what
the jsdoc parser uses for text) but the result is worse. I also tried
reusing `js-fill-paragraph' but that fails as well. The result of this
patch is that `M-q' doesn't change anything anymore in these blocks. I
will report a bug and seek assistance to fix it if this patch is merged.

Best,

-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-jsdoc-support-to-js-ts-mode.patch --]
[-- Type: text/patch, Size: 3971 bytes --]

From 4a0682577accc094aeccb3f51988cb5e0bcabe03 Mon Sep 17 00:00:00 2001
From: Damien Cassou <damien@cassou.me>
Date: Fri, 14 Jun 2024 10:46:42 +0200
Subject: [PATCH] Add jsdoc support to js-ts-mode

* lisp/progmodes/js.el (js--treesit-font-lock-settings): Add jsdoc
font-lock settings.
(js--treesit-jsdoc-beginning-regexp): New variable to match the
beginning of a jsdoc block.
(js-ts-mode): Add jsdoc support. Save the 'javascript parser to
`treesit-primary-parser'. Configure `treesit-range-settings' to
use a jsdoc parser within a JavaScript file.
(js-ts-language-at-point): New function to return either 'jsdoc or
'javascript depending on where the point is.
---
 lisp/progmodes/js.el | 54 ++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 52 insertions(+), 2 deletions(-)

diff --git a/lisp/progmodes/js.el b/lisp/progmodes/js.el
index f5629ff8fbe..529b31669ed 100644
--- a/lisp/progmodes/js.el
+++ b/lisp/progmodes/js.el
@@ -3634,7 +3634,32 @@ js--treesit-font-lock-settings
    :language 'javascript
    :feature 'escape-sequence
    :override t
-   '((escape_sequence) @font-lock-escape-face))
+   '((escape_sequence) @font-lock-escape-face)
+
+   :language 'jsdoc
+   :override t
+   :feature 'keyword
+   '((tag_name) @font-lock-keyword-face)
+
+   :language 'jsdoc
+   :override t
+   :feature 'bracket
+   '((["{" "}"]) @font-lock-bracket-face)
+
+   :language 'jsdoc
+   :override t
+   :feature 'property
+   '((type) @font-lock-variable-use-face)
+
+   :language 'jsdoc
+   :override t
+   :feature 'definition
+   '((identifier) @font-lock-variable-name-face)
+
+   :language 'jsdoc
+   :override t
+   :feature 'comment
+   '((description) @font-lock-comment-face))
   "Tree-sitter font-lock settings.")
 
 (defun js--fontify-template-string (node override start end &rest _)
@@ -3857,6 +3882,9 @@ js--treesit-sexp-nodes
   "Nodes that designate sexps in JavaScript.
 See `treesit-thing-settings' for more information.")
 
+(defvar js--treesit-jsdoc-beginning-regexp (rx bos "/**")
+  "Regular expression matching the beginning of a jsdoc block comment.")
+
 ;;;###autoload
 (define-derived-mode js-ts-mode js-base-mode "JavaScript"
   "Major mode for editing JavaScript.
@@ -3882,7 +3910,8 @@ js-ts-mode
     (setq-local syntax-propertize-function #'js-ts--syntax-propertize)
 
     ;; Tree-sitter setup.
-    (treesit-parser-create 'javascript)
+    (setq-local treesit-primary-parser (treesit-parser-create 'javascript))
+
     ;; Indent.
     (setq-local treesit-simple-indent-rules js--treesit-indent-rules)
     ;; Navigation.
@@ -3909,6 +3938,16 @@ js-ts-mode
                   ( assignment constant escape-sequence jsx number
                     pattern string-interpolation)
                   ( bracket delimiter function operator property)))
+
+    (when (treesit-ready-p 'jsdoc t)
+      (setq-local treesit-range-settings
+                  (treesit-range-rules
+                   :embed 'jsdoc
+                   :host 'javascript
+                   `(((comment) @capture (:match ,js--treesit-jsdoc-beginning-regexp @capture))))))
+
+    (setq-local treesit-language-at-point-function #'js-ts-language-at-point)
+
     ;; Imenu
     (setq-local treesit-simple-imenu-settings
                 `(("Function" "\\`function_declaration\\'" nil nil)
@@ -3950,6 +3989,17 @@ js-ts--syntax-propertize
         (put-text-property ns (1+ ns) 'syntax-table syntax)
         (put-text-property (1- ne) ne 'syntax-table syntax)))))
 
+(defun js-ts-language-at-point (point)
+  "Return the language at POINT."
+  (let ((node (treesit-node-at point 'javascript)))
+    (if (and (treesit-ready-p 'jsdoc)
+             (equal (treesit-node-type node) "comment")
+             (string-match-p
+              js--treesit-jsdoc-beginning-regexp
+              (treesit-node-text node)))
+        'jsdoc
+      'javascript)))
+
 ;;;###autoload
 (define-derived-mode js-json-mode prog-mode "JSON"
   :syntax-table js-mode-syntax-table
-- 
2.44.1


[-- Attachment #3: after.png --]
[-- Type: image/png, Size: 10593 bytes --]

[-- Attachment #4: before.png --]
[-- Type: image/png, Size: 9898 bytes --]

bug#71550: [PATCH] Add jsdoc support to js-ts-mode

[Dmitry Gutov]

Eli, is this okay for master (Emacs 30), or should it wait until the 
release branch is cut?

On 14/06/2024 15:33, Damien Cassou wrote:
> Tags: patch
> 
> Hi,
> 
> jsdoc [1] is a special syntax to document JavaScript code. The attached
> patch adds a jsdoc parser and font-lock settings to files using the
> `js-ts-mode' major mode if the jsdoc grammar is available. Before/after
> screenshots are attached to this email.
> 
> [1] jsdoc: https://jsdoc.app/
> 
> The new code does *not* make `js-ts-mode' dependent on the availability
> of the jsdoc grammar: instead, `js-ts-mode' will keep working as it
> works today if the jsdoc grammar is absent.
> 
> The support for paragraph filling currently in master is broken because
> the prefix '*' isn't added at the beginning of lines when filling
> documentation blocks. I tried changing the value of
> `c-ts-common--comment-regexp' to include "description" (as this is what
> the jsdoc parser uses for text) but the result is worse. I also tried
> reusing `js-fill-paragraph' but that fails as well. The result of this
> patch is that `M-q' doesn't change anything anymore in these blocks. I
> will report a bug and seek assistance to fix it if this patch is merged.

bug#71550: [PATCH] Add jsdoc support to js-ts-mode

[Eli Zaretskii]

> Date: Sat, 22 Jun 2024 00:53:43 +0300
> From: Dmitry Gutov <dmitry@gutov.dev>
> 
> Eli, is this okay for master (Emacs 30), or should it wait until the 
> release branch is cut?

It's okay to install this now, thanks.

bug#71550: [PATCH] Add jsdoc support to js-ts-mode

[Dmitry Gutov]

On 22/06/2024 10:08, Eli Zaretskii wrote:
>> Date: Sat, 22 Jun 2024 00:53:43 +0300
>> From: Dmitry Gutov<dmitry@gutov.dev>
>>
>> Eli, is this okay for master (Emacs 30), or should it wait until the
>> release branch is cut?
> It's okay to install this now, thanks.

Thank you, I've pushed it to emacs-30.

And thanks do Damien!

The follow-ups (filling-related?) will go to separate reports.