As discussed in #61, if you attempt to use `defer multierr.AppendInvoke`
with an error that is not a named return, the system will lose the
error.
```go
func fails() error { return errors.New("great sadness") }
func foo() error {
var err error
defer multierr.AppendInvoke(&err, multierr.Invoke(fails))
return err
}
func main() {
fmt.Println(foo()) // nil
}
```
https://go.dev/play/p/qK4NR-VYLvo
This isn't something the library can address because of how defers work.
This change adds a warning about the error variable being a named return
in all places where we suggest use of multierr with defer.
While we're at it, this makes use of the new `[Foo]` godoc syntax to
generate links to other functions in the package in "See Foo"
statements in the documentation.
As discussed in #61, if you attempt to use
defer multierr.AppendInvokewith an error that is not a named return, the system will lose the
error.
https://go.dev/play/p/qK4NR-VYLvo
This isn't something the library can address because of how defers work.
This change adds a warning about the error variable being a named return
in all places where we suggest use of multierr with defer.
While we're at it, this makes use of the new
[Foo]godoc syntax togenerate links to other functions in the package in "See Foo"
statements in the documentation.