bug#60805: [PATCH] Extend go-ts-mode with command to add docstring to function

[Evgeni Kolev <evgenysw@gmail.com>]

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

On Fri, Jan 20, 2023 at 10:39 PM Theodor Thornhill <theo@thornhill.no> wrote:
>
> By the way, the patch doesn't apply cleanly on my system, could you
> resend the patch as an attachment, maybe?  And also, have you done the
> paperwork for emacs contributions?
>

Sure, I'll attach it, and attach any future patches. I signed the
paperwork 4-5 years ago when making changes in perl-mode.
https://git.savannah.gnu.org/cgit/emacs.git/log/?qt=author&q=evgeni+kolev&showmsg=1

On Sat, Jan 21, 2023 at 5:30 AM Randy Taylor <dev@rjt.dev> wrote:
>
>
> Otherwise, it looks good to me. Thanks for continuing to work on go-ts-mode, I should probably stop slacking so much ;).

Thank you for starting go-ts-mode - I was pleasantly surprised when I
found out it existed and even better - was part of emacs!

On Sat, Jan 21, 2023 at 8:48 AM Eshel Yaron <me@eshelyaron.com> wrote:
>
>
> A quick thought from someone interested in using this new command:
>
> IMO the current implementation is a bit too opinionated to be really
> useful.  Inserting the function's name at the beginning of the comment
> is not always desired because different teams have different conventions
> for doc comments, and sometimes you just want to add a nolint
> directive[0] which again doesn't start with the function's name.
>
> My suggestion is to add some way for users to customize/extend the
> contents of the inserted doc comment.  One option is to have a variable
> that'll hold a function responsible for determining the text of the
> comment.  This variable can then default to a function that returns the
> current Go function's name.

While I agree users should be able to customize, this particular
example is too much of a corner case.

For example, which Go functions/types need a docstring - all exported
ones, and possibly some unexported; on the other hand, adding linter
directives is so rare, you need to have a very good reason to add such
exceptions. Team-accepted exceptions are stored as accompanying config
files; example https://staticcheck.io/docs/configuration/#configuration-files

We can add a variable holding a function which will take a defun
treesit node as input, and return text. It's simple from
implementation point of view.

However, I don't see how this will make Emacs more useful - let's say
the user wants to enter a linter comment, will they:
1. modify the customization variable to another function, then C-c
C-d, then revert the customization variable; or
2. they can just enter the linter comment

As long as entering linter comments is rare, I believe the user will just do 2.

[-- Attachment #2: 0001-Extend-go-ts-mode-with-command-to-add-docstring-to-f.patch --]
[-- Type: application/octet-stream, Size: 3385 bytes --]

From 0c19a235c5775857cbf15676e3ee7196b158f0d1 Mon Sep 17 00:00:00 2001
From: Evgeni Kolev <evgenysw@gmail.com>
Date: Sat, 14 Jan 2023 08:28:06 +0200
Subject: [PATCH] Extend go-ts-mode with command to add docstring to function

go-ts-mode is extended with command go-ts-mode-docstring which adds
docstring comment to the defun at point. If a comment already exists,
the point is instead moved to the top-most comment line. The command
is bound to "C-c C-d".

* lisp/progmodes/go-ts-mode.el (go-ts-mode): Extend docstring.
(go-ts-mode-docstring): New function.
(go-ts-mode--comment-on-previous-line-p ): New function.
(go-ts-mode-map): New map variable.
* etc/NEWS: Mention the change.
---
 etc/NEWS                     |  8 ++++++++
 lisp/progmodes/go-ts-mode.el | 35 ++++++++++++++++++++++++++++++++++-
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/etc/NEWS b/etc/NEWS
index f111d401df8..1715cbb83b1 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -178,6 +178,14 @@ the new argument NEW-BUFFER non-nil, it will use a new buffer instead.
 Interactively, invoke 'eww-open-file' with a prefix argument to
 activate this behavior.
 
+** go-ts-mode
+
++++
+*** New command 'go-ts-mode-docstring'.
+This command adds a docstring comment to the current defun.  If a
+comment already exists, point is only moved to the comment.  It is
+bound to 'C-c C-d' in 'go-ts-mode'.
+
 \f
 * New Modes and Packages in Emacs 30.1
 
diff --git a/lisp/progmodes/go-ts-mode.el b/lisp/progmodes/go-ts-mode.el
index 64e761d2f72..be5a69c2ec4 100644
--- a/lisp/progmodes/go-ts-mode.el
+++ b/lisp/progmodes/go-ts-mode.el
@@ -177,9 +177,16 @@ go-ts-mode--font-lock-settings
 ;;;###autoload
 (add-to-list 'auto-mode-alist '("\\.go\\'" . go-ts-mode))
 
+(defvar-keymap go-ts-mode-map
+  :doc "Keymap used in Go mode, powered by tree-sitter"
+  :parent prog-mode-map
+  "C-c C-d" #'go-ts-mode-docstring)
+
 ;;;###autoload
 (define-derived-mode go-ts-mode prog-mode "Go"
-  "Major mode for editing Go, powered by tree-sitter."
+  "Major mode for editing Go, powered by tree-sitter.
+
+\\{go-ts-mode-map}"
   :group 'go
   :syntax-table go-ts-mode--syntax-table
 
@@ -274,6 +281,32 @@ go-ts-mode--other-type-node-p
    (not (go-ts-mode--struct-node-p node))
    (not (go-ts-mode--alias-node-p node))))
 
+(defun go-ts-mode-docstring ()
+  "Add a docstring comment for the current defun.
+The added docstring is prefilled with the defun's name.  If the
+comment already exists, jump to it."
+  (interactive)
+  (when-let ((defun-node (treesit-defun-at-point)))
+    (goto-char (treesit-node-start defun-node))
+    (if (go-ts-mode--comment-on-previous-line-p)
+        ;; go to top comment line
+        (while (go-ts-mode--comment-on-previous-line-p)
+          (forward-line -1))
+      (insert "// " (treesit-defun-name defun-node))
+      (newline)
+      (backward-char))))
+
+(defun go-ts-mode--comment-on-previous-line-p ()
+  "Return t if the previous line is a comment."
+  (when-let ((point (- (pos-bol) 1))
+             ((> point 0))
+             (node (treesit-node-at point)))
+    (and
+     ;; check point is actually inside the found node
+     ;; treesit-node-at can return nodes after point
+     (<= (treesit-node-start node) point (treesit-node-end node))
+     (string-equal "comment" (treesit-node-type node)))))
+
 ;; go.mod support.
 
 (defvar go-mod-ts-mode--syntax-table
-- 
2.30.2