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

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

[Evgeni Kolev]

[CC Randy Taylor, author of go-ts-mode]

This patch extends go-ts-mode with a command to add docstring to
current function. If a comment already exists, the point is instead
moved to the top-most comment line.

Tested with the following Go code:

First test, with this input, point inside the function body.
```
func test1(a, b int) int {
    return a + b
}
```

Pressing C-c C-d results in:
```
// test1
func test1(a, b int) int {
    return a + b
}
```

Second test, with this input, point inside the function body.
```
// multiple line
// pre-existing comment
func test2(a, b int) int {
    return a + b
}
```
Pressing C-c C-d does not change the buffer, point is moved to
beginning of  this line "// multiple line".

Third test, the new behavior works identically for all "defun" types
recognized by go-ts-mode:
```
type MyInt = int
type Option func(s string)
type List[T any] struct {
    head, tail *element[T]
}
type Number interface {
    int64 | float64
}
```

The patch is below.

commit e47f7f256a71aaae2ed645c0ea67afc90e956071
Author: Evgeni Kolev <evgenysw@gmail.com>
Date:   Sat Jan 14 08:28:06 2023 +0200

    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.

    * lisp/progmodes/go-ts-mode.el (go-ts-mode): Extend docstring.
    (go-ts-mode-docstring): New function.
    (go-ts-mode-map): New map variable.

diff --git a/lisp/progmodes/go-ts-mode.el b/lisp/progmodes/go-ts-mode.el
index 64e761d2f72..f8b0289ca5b 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,25 @@ 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 docstring for the current function if it does not
+exists. Otherwise, jump to it."
+    (interactive)
+    (when-let* ((defun-node (treesit-defun-at-point))
+                (defun-name (treesit-defun-name defun-node))
+                (defun-start (treesit-node-start defun-node)))
+      (let ((prev-node (treesit-node-at (- defun-start 1))))
+        (if (string-equal "comment" (treesit-node-type prev-node))
+            (progn
+              (goto-char (treesit-node-start prev-node))
+              ;; go to the top-most comment line
+              (while (string-equal "comment" (treesit-node-type
(treesit-node-at (- (point) 1))))
+                (forward-line -1)))
+          (goto-char defun-start)
+          (newline)
+          (forward-line -1)
+          (insert "// " defun-name)))))
+
 ;; go.mod support.

 (defvar go-mod-ts-mode--syntax-table

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

[Eli Zaretskii]

> Cc: Randy Taylor <dev@rjt.dev>
> From: Evgeni Kolev <evgenysw@gmail.com>
> Date: Sat, 14 Jan 2023 08:45:31 +0200
> 
> [CC Randy Taylor, author of go-ts-mode]
> 
> This patch extends go-ts-mode with a command to add docstring to
> current function. If a comment already exists, the point is instead
> moved to the top-most comment line.

Thanks.  When accepted, this should go to the master branch, as it's a
new feature.

> First test, with this input, point inside the function body.
> ```
> func test1(a, b int) int {
>     return a + b
> }
> ```
> 
> Pressing C-c C-d results in:
> ```
> // test1
> func test1(a, b int) int {
>     return a + b
> }
> ```

Is this really the best Emacs can do to produce such a comment?  It's
not a very useful comment, is it?  I understand that the user is then
expected to add some more meaningful text to make the comment useful,
but I'm asking whether Emacs could collect more information about the
function, and provide a skeleton of a useful doc comment for the user
to fill.

What do other IDEs do for this kind of functionality?

>     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,
                                             ^^
Please observe our convention of leaving 2 spaces between sentences.

> +(defun go-ts-mode-docstring ()
> +    "Add docstring for the current function if it does not
> +exists. Otherwise, jump to it."

The first line of a doc string should be a complete sentence.

Finally, this change needs a NEWS entry.

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

[Theodor Thornhill via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> Cc: Randy Taylor <dev@rjt.dev>
>> From: Evgeni Kolev <evgenysw@gmail.com>
>> Date: Sat, 14 Jan 2023 08:45:31 +0200
>> 
>> [CC Randy Taylor, author of go-ts-mode]
>> 
>> This patch extends go-ts-mode with a command to add docstring to
>> current function. If a comment already exists, the point is instead
>> moved to the top-most comment line.
>
> Thanks.  When accepted, this should go to the master branch, as it's a
> new feature.
>
>> First test, with this input, point inside the function body.
>> ```
>> func test1(a, b int) int {
>>     return a + b
>> }
>> ```
>> 
>> Pressing C-c C-d results in:
>> ```
>> // test1
>> func test1(a, b int) int {
>>     return a + b
>> }
>> ```
>
> Is this really the best Emacs can do to produce such a comment?  It's
> not a very useful comment, is it?  I understand that the user is then
> expected to add some more meaningful text to make the comment useful,
> but I'm asking whether Emacs could collect more information about the
> function, and provide a skeleton of a useful doc comment for the user
> to fill.
>
> What do other IDEs do for this kind of functionality?
>
>>     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,
>                                              ^^
> Please observe our convention of leaving 2 spaces between sentences.
>
>> +(defun go-ts-mode-docstring ()
>> +    "Add docstring for the current function if it does not
>> +exists. Otherwise, jump to it."
>
> The first line of a doc string should be a complete sentence.
>
> Finally, this change needs a NEWS entry.


Should we maybe generalize this into something all *-ts-modes can use?

Maybe it also could support some syntax to be used by for example
yasnippet?  There are examples on how to do so in eglot.el, if I'm not
mistaken.

Theo

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

[Eli Zaretskii]

> From: Theodor Thornhill <theo@thornhill.no>
> Cc: Evgeni Kolev <evgenysw@gmail.com>,  dev@rjt.dev,  60805@debbugs.gnu.org
> Date: Sat, 14 Jan 2023 12:43:21 +0100
> 
> Should we maybe generalize this into something all *-ts-modes can use?

I don't know how widespread are such features with other languages.

> Maybe it also could support some syntax to be used by for example
> yasnippet?  There are examples on how to do so in eglot.el, if I'm not
> mistaken.

Maybe.  I'd have to see code to have an opinion.  Emacs never had such
features, AFAIR.

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

[Theodor Thornhill via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Theodor Thornhill <theo@thornhill.no>
>> Cc: Evgeni Kolev <evgenysw@gmail.com>,  dev@rjt.dev,  60805@debbugs.gnu.org
>> Date: Sat, 14 Jan 2023 12:43:21 +0100
>> 
>> Should we maybe generalize this into something all *-ts-modes can use?
>
> I don't know how widespread are such features with other languages.
>
>> Maybe it also could support some syntax to be used by for example
>> yasnippet?  There are examples on how to do so in eglot.el, if I'm not
>> mistaken.
>
> Maybe.  I'd have to see code to have an opinion.  Emacs never had such
> features, AFAIR.


From eglot.el:
```
(defun eglot--snippet-expansion-fn ()
  "Compute a function to expand snippets.
Doubles as an indicator of snippet support."
  (and (boundp 'yas-minor-mode)
       (symbol-value 'yas-minor-mode)
       'yas-expand-snippet))
```

So if yasnippet is available, it will be expanded.  We could have a
similar function in treesit.el, adding support for such "skeleton"
insertion features.  A simple example for javascript could be:

```
import ${2:$1} from '${1:moduleName}';
```

Which could be plugged into this patch, if I'm not mistaken.

Theo

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

[Evgeni Kolev]

Regarding snippet support - I think it makes sense in general, but for
this particular patch, not really.

Go's docstrings don't typically follow a strict template, instead they
are a human-readable comment which tries to be short but also describe
any corner cases - very similar to Emacs' doc strings. I'm pasting
below a few Go examples from https://go.dev/doc/comment

> Is this really the best Emacs can do to produce such a comment? ... I'm asking whether Emacs could collect more information about the function, and provide a skeleton of a useful doc comment for the user to fill.

Emacs could fill in the inputs and outputs as variable names but I
don't think this will be very useful because the doc strings don't
follow a strict template (as mentioned above). Something like this is
an option:

```
// sum accepts a and b and returns an int
func sum(a, b int) int {
    return a + b
}
```

The above approach wouldn't work so well on non-functions.

> What do other IDEs do for this kind of functionality?

I'll do some research, I haven't used other IDEs.

> Please observe our convention of leaving 2 spaces between sentences.

Sorry, I didn't run checkdoc before posting the patch.

Go example docstrings are below.

```
// A Buffer is a variable-sized buffer of bytes with Read and Write methods.
// The zero value for Buffer is an empty buffer ready to use.
type Buffer struct {
    ...
}
...

// Copy copies from src to dst until either EOF is reached
// on src or an error occurs. It returns the total number of bytes
// written and the first error encountered while copying, if any.
//
// A successful Copy returns err == nil, not err == EOF. ...
func Copy(dst Writer, src Reader) (n int64, err error) {
    ...
}

// Exit causes the current program to exit with the given status code.
// Conventionally, code zero indicates success, non-zero an error.
// The program terminates immediately; deferred functions are not run....
func Exit(code int) {
    ...
}
```

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

[Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Theodor Thornhill <theo@thornhill.no>
>> Cc: Evgeni Kolev <evgenysw@gmail.com>,  dev@rjt.dev,  60805@debbugs.gnu.org
>> Date: Sat, 14 Jan 2023 12:43:21 +0100
>> 
>> Should we maybe generalize this into something all *-ts-modes can use?
>
> I don't know how widespread are such features with other languages.
>
>> Maybe it also could support some syntax to be used by for example
>> yasnippet?  There are examples on how to do so in eglot.el, if I'm not
>> mistaken.
>
> Maybe.  I'd have to see code to have an opinion.  Emacs never had such
> features, AFAIR.

FWIW as a possible reference, sweeprolog.el has a (very) similar feature
in sweeprolog-mode for adding documentation comments.  From the manual[0]:

Key: C-c C-d (sweeprolog-document-predicate-at-point)
    Insert PlDoc documentation comment for the predicate at or above point.

There's a user option that determines how this command populates the
initial doc comment, by default it reads some information in the
minibuffer and use it to create a fully structured comment.


Cheers,
Eshel


[0] https://eshelyaron.com/sweep.html#sweeprolog-pldoc or (info "(sweep)Documenting Code")

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

[Theodor Thornhill via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Evgeni Kolev <evgenysw@gmail.com> writes:

> Regarding snippet support - I think it makes sense in general, but for
> this particular patch, not really.
>
> Go's docstrings don't typically follow a strict template, instead they
> are a human-readable comment which tries to be short but also describe
> any corner cases - very similar to Emacs' doc strings. I'm pasting
> below a few Go examples from https://go.dev/doc/comment
>
>> Is this really the best Emacs can do to produce such a comment? ... I'm asking
>> whether Emacs could collect more information about the function, and provide a
>> skeleton of a useful doc comment for the user to fill.
>
> Emacs could fill in the inputs and outputs as variable names but I
> don't think this will be very useful because the doc strings don't
> follow a strict template (as mentioned above). Something like this is
> an option:
>
> ```
> // sum accepts a and b and returns an int
> func sum(a, b int) int {
>     return a + b
> }
> ```

Sure, I won't argue :)

What about something like this to locate the first comment above a
defun?

Theo

(defun move-to-top-comment ()
  (interactive)
  (save-restriction
    (narrow-to-defun t)
    (let ((comments (cdr (treesit-induce-sparse-tree
                          (treesit-buffer-root-node)
                          (lambda (n)
                            (equal (treesit-node-type n)
                                   "comment"))))))
      (goto-char
       (apply #'treesit-node-start (car comments))))))

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

[Evgeni Kolev]

> What about something like this to locate the first comment above a
> defun?
>
> Theo
>
> (defun move-to-top-comment ()
>   (interactive)
>   (save-restriction
>     (narrow-to-defun t)
>     (let ((comments (cdr (treesit-induce-sparse-tree
>                           (treesit-buffer-root-node)
>                           (lambda (n)
>                             (equal (treesit-node-type n)
>                                    "comment"))))))
>       (goto-char
>        (apply #'treesit-node-start (car comments))))))

Thank you for the suggestion Theo, I learned a lot about
treesit-induce-sparse-tree! When I tested your suggestion however, I
found that the tree sitter functions don't take into account the
narrowing, instead they operate on the whole buffer. So the 'comments'
variable holds all the buffer's comments, not just the ones above the
current defun. The suggestion works because (car comments) returns the
top comment in the buffer and goto-char tries to go to it, but is
restricted by the narrowing. In other words, this works as well:

(defun move-to-top-comment ()
  (interactive)
  (save-restriction
    (narrow-to-defun t)
    (goto-char 0)))

I'm providing an updated patch below. The algorithm for finding the
top comment is a while-loop which does (forward-line -1) until the
previous treesit sibling is not a comment.

I've executed 'checkdoc' this time, and added an /etc/NEWS entry.

The patch is below. Any feedback is appreciated!

From 5cd8a1cb4e491b9db6ed586d88ac79ab52e395f0 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.

* lisp/progmodes/go-ts-mode.el (go-ts-mode): Extend docstring.
(go-ts-mode-docstring): New function.
(go-ts-mode-map): New map variable.
* etc/NEWS: Mention the change.
---
 etc/NEWS                     |  8 ++++++++
 lisp/progmodes/go-ts-mode.el | 30 +++++++++++++++++++++++++++++-
 2 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/etc/NEWS b/etc/NEWS
index cde6783349f..68ad90ab189 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -165,6 +165,14 @@ the new argument 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'.
+

 * 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..cc8171e9be6 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,27 @@ 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))
+             (defun-name (treesit-defun-name defun-node)))
+    (let ((prev-node (treesit-node-prev-sibling defun-node t)))
+      (if (string-equal "comment" (treesit-node-type prev-node))
+          ;; go to the top-most comment line
+          (progn
+            (goto-char (treesit-node-start prev-node))
+            (while-let ((curr-node (treesit-node-at (point)))
+                        (prev-node (treesit-node-prev-sibling curr-node t))
+                        ((string-equal "comment" (treesit-node-type
prev-node))))
+              (forward-line -1)))
+        (goto-char (treesit-node-start defun-node))
+        (newline)
+        (forward-line -1)
+        (insert "// " defun-name)))))
+
 ;; go.mod support.

 (defvar go-mod-ts-mode--syntax-table
-- 
2.30.2

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

[Theodor Thornhill via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Evgeni Kolev <evgenysw@gmail.com> writes:

>> What about something like this to locate the first comment above a
>> defun?
>>
>> Theo
>>
>> (defun move-to-top-comment ()
>>   (interactive)
>>   (save-restriction
>>     (narrow-to-defun t)
>>     (let ((comments (cdr (treesit-induce-sparse-tree
>>                           (treesit-buffer-root-node)
>>                           (lambda (n)
>>                             (equal (treesit-node-type n)
>>                                    "comment"))))))
>>       (goto-char
>>        (apply #'treesit-node-start (car comments))))))
>
> Thank you for the suggestion Theo, I learned a lot about
> treesit-induce-sparse-tree! When I tested your suggestion however, I
> found that the tree sitter functions don't take into account the
> narrowing, instead they operate on the whole buffer. So the 'comments'
> variable holds all the buffer's comments, not just the ones above the
> current defun. The suggestion works because (car comments) returns the
> top comment in the buffer and goto-char tries to go to it, but is
> restricted by the narrowing. In other words, this works as well:
>
> (defun move-to-top-comment ()
>   (interactive)
>   (save-restriction
>     (narrow-to-defun t)
>     (goto-char 0)))
>

In that case, maybe it is even simpler to do something like:

(defun defun-comment-p ()
  (interactive)
  (save-restriction
    (narrow-to-defun t)
    (goto-char (point-min))
    (equal
      (treesit-node-type (treesit-node-at (point)))
      "comment")))

But sure, I won't argue :)


However, now this code would act on code such as:

```
//go:generate protoc .........

// some docstring
func main() {

}
```

And return point on the line with go:generate.  Is that desired?


> I'm providing an updated patch below. The algorithm for finding the
> top comment is a while-loop which does (forward-line -1) until the
> previous treesit sibling is not a comment.
>
> I've executed 'checkdoc' this time, and added an /etc/NEWS entry.
>
> The patch is below. Any feedback is appreciated!
>
> From 5cd8a1cb4e491b9db6ed586d88ac79ab52e395f0 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
>

> +(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)
> +

Should we bind something to the C-c prefix?  I thought this was
"user-reserved", so a user should bind them themselves.

>  ;;;###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,27 @@ 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))
> +             (defun-name (treesit-defun-name defun-node)))
> +    (let ((prev-node (treesit-node-prev-sibling defun-node t)))
> +      (if (string-equal "comment" (treesit-node-type prev-node))
> +          ;; go to the top-most comment line
> +          (progn
> +            (goto-char (treesit-node-start prev-node))
> +            (while-let ((curr-node (treesit-node-at (point)))
> +                        (prev-node (treesit-node-prev-sibling curr-node t))
> +                        ((string-equal "comment" (treesit-node-type
> prev-node))))
> +              (forward-line -1)))
> +        (goto-char (treesit-node-start defun-node))
> +        (newline)
> +        (forward-line -1)
> +        (insert "// " defun-name)))))
> +
>  ;; go.mod support.
>
>  (defvar go-mod-ts-mode--syntax-table
> -- 
> 2.30.2

Thanks,
Theo

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

[Evgeni Kolev]

> In that case, maybe it is even simpler to do something like:
>
> (defun defun-comment-p ()
>   (interactive)
>   (save-restriction
>     (narrow-to-defun t)
>     (goto-char (point-min))
>     (equal
>       (treesit-node-type (treesit-node-at (point)))
>       "comment")))

BTW I've noticed M-x mark-defun doesn't work correctly in some cases
with go-ts-mode (other *-gs-modes might also be affected, I haven't
tested). I wonder if narrow-to-defun could also be affected. For
example, with this Go code:

```
package main

func main() {

}

// some docstring
func main1() {

}
```
With the point in the body of "main1()", running M-x mark-defun marks
the blank line between the two functions instead of main1(). I'll
report this as a separate bug.

> However, now this code would act on code such as:
>
> ```
> //go:generate protoc .........
>
> // some docstring
> func main() {
>
> }
> ```
>
> And return point on the line with go:generate.  Is that desired?

I'd prefer to _not_ add special handling for "//go:..." comments which
are somewhat rare and typically put on the very first line of the
file. For your particular example the point should be put on "// some
docstring" because there's a separating blank line. This is not the
behavior with my patch - I'll try to improve it.


> Should we bind something to the C-c prefix?  I thought this was
> "user-reserved", so a user should bind them themselves.

I believe only "C-c letter" is user-reserved. I've drawn this
conclusion from here
https://www.gnu.org/software/emacs/manual/html_node/elisp/Key-Binding-Conventions.html

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

[Evgeni Kolev]

I'm sending an updated patch. The improvement is that empty lines are
not considered comments. Example:
```
// unrelated comment

// docstring
func sum(a, b int) int {
    return a + b
}
```
With point in the function body, C-c C-d jumps to "// docstring"
instead of "// unrelated comment".

Patch is below.

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'.
+

 * 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

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

[Theodor Thornhill via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Evgeni Kolev <evgenysw@gmail.com> writes:

> I'm sending an updated patch. The improvement is that empty lines are
> not considered comments. Example:
> ```
> // unrelated comment
>
> // docstring
> func sum(a, b int) int {
>     return a + b
> }
> ```
> With point in the function body, C-c C-d jumps to "// docstring"
> instead of "// unrelated comment".
>
> Patch is below.
>

Thanks!

@Randy, anything you want to add?

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?

Theo

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

[Randy Taylor]

On Friday, January 20th, 2023 at 15:39, Theodor Thornhill via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org> wrote:
> 
> Evgeni Kolev evgenysw@gmail.com writes:
> 
> > I'm sending an updated patch. The improvement is that empty lines are
> > not considered comments. Example:
> > ```
> > // unrelated comment
> > 
> > // docstring
> > func sum(a, b int) int {
> > return a + b
> > }
> > ```
> > With point in the function body, C-c C-d jumps to "// docstring"
> > instead of "// unrelated comment".
> > 
> > Patch is below.
> 
> 
> Thanks!
> 
> @Randy, anything you want to add?

Only thing I would consider is if C-c C-d is the best keybind for it. go-mode seems to use C-c C-d to describe the expression at point. Not sure what else we would use C-c C-d for so it seems fine to me. And if we decide to have something similar to this across other ts modes, it would be nice if we could keep them consistent. If everyone's happy with C-c C-d, then I am too.

Otherwise, it looks good to me. Thanks for continuing to work on go-ts-mode, I should probably stop slacking so much ;).

> 
> By the way, the patch doesn't apply cleanly on my system, could you
> resend the patch as an attachment, maybe? 

Indeed. Evgeni, in the future can you submit all your patches as attachments? I've never been able to apply them cleanly and I'm not sure why.

> And also, have you done the paperwork for emacs contributions?

He should be good here, he submitted a big go-ts-mode patch a few weeks ago :).

> 
> Theo

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

[Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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.

Thanks,
Eshel


[0] https://golangci-lint.run/usage/false-positives/#nolint-directive

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

[Theodor Thornhill via Bug reports for GNU Emacs, the Swiss army knife of text editors]

On 21 January 2023 07:48:48 CET, 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.
>
>Thanks,
>Eshel
>
>
>[0] https://golangci-lint.run/usage/false-positives/#nolint-directive


Why not just
(insert "// ")

Theo

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

[Evgeni Kolev]

[-- 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

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

[Theodor Thornhill via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Evgeni Kolev <evgenysw@gmail.com> writes:

> 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
>

Thanks!

Applied to master - keep them coming :)

Theo

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

[Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Evgeni Kolev <evgenysw@gmail.com> writes:

> 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.

You don't need to modify the customization variable and restore it, you
just need to define a specialized command that let-binds it and calls
go-ts-mode-docstring.  So I could have a custom command for directives
or other formats that's as simple as:

(defun my/go-insert-custom-docstring ()
  (interactive)
  (let ((go-ts-mode-docstring-function #'my/go-custom-docstring))
    (go-ts-mode-docstring)))

With the current implementation, writing such a command would basically
require duplicating the code of go-ts-mode-docstring expect for the part
that inserts the Go function's name, right?  That's not that such a big
problem of course, but not ideal either IMO.


Eshel