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" <bug-gnu-emacs@gnu.org>]

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