From: Evgeni Kolev <evgenysw@gmail.com>
To: Theodor Thornhill <theo@thornhill.no>
Cc: dev@rjt.dev, Eli Zaretskii <eliz@gnu.org>, 60805@debbugs.gnu.org
Subject: bug#60805: [PATCH] Extend go-ts-mode with command to add docstring to function
Date: Wed, 18 Jan 2023 08:26:39 +0200 [thread overview]
Message-ID: <CAMCrgaVJqG7eOJbbg0k+KN9i0xDg3raxE8vUTsmzQhYFXk=Bhg@mail.gmail.com> (raw)
In-Reply-To: <87sfgdtga2.fsf@thornhill.no>
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) {
...
}
```
next prev parent reply other threads:[~2023-01-18 6:26 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-01-14 6:45 bug#60805: [PATCH] Extend go-ts-mode with command to add docstring to function Evgeni Kolev
2023-01-14 7:48 ` Eli Zaretskii
2023-01-14 11:43 ` Theodor Thornhill via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-01-14 12:24 ` Eli Zaretskii
2023-01-14 13:08 ` Theodor Thornhill via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-01-18 6:26 ` Evgeni Kolev [this message]
2023-01-18 11:59 ` Theodor Thornhill via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-01-20 9:41 ` Evgeni Kolev
2023-01-20 10:14 ` Theodor Thornhill via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-01-20 11:39 ` Evgeni Kolev
2023-01-20 14:56 ` Evgeni Kolev
2023-01-20 20:39 ` Theodor Thornhill via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-01-21 3:30 ` Randy Taylor
2023-01-21 6:48 ` Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-01-21 7:34 ` Theodor Thornhill via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-01-21 14:39 ` Evgeni Kolev
2023-01-21 20:37 ` Theodor Thornhill via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-01-21 21:26 ` Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-01-18 7:46 ` Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAMCrgaVJqG7eOJbbg0k+KN9i0xDg3raxE8vUTsmzQhYFXk=Bhg@mail.gmail.com' \
--to=evgenysw@gmail.com \
--cc=60805@debbugs.gnu.org \
--cc=dev@rjt.dev \
--cc=eliz@gnu.org \
--cc=theo@thornhill.no \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).