bug-gnu-emacs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Evgeni Kolev
Subject: bug#60805: [PATCH] Extend go-ts-mode with command to add docstring to function
Date: Wed, 18 Jan 2023 08:26:39 +0200

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) {
    ...
}
```





reply via email to

[Prev in Thread] Current Thread [Next in Thread]