all: simplify standard library examples #36417
Comments
One's home directory could be huge, though. How about It's true that the volume and quality of reviews hasn't been keeping up with the amount of new contributors over the past few years. I'm not sure that there's a good solution to this; having fewer examples, or keeping new contributors waiting for a long time both seem like worse situations. Will you be sending CLs as part of this issue, or is this a call for others to help? :) |
We can discuss the details on CLs, I suggested an alternative just to explain my point :)
I am hoping this becomes a placeholder issue and everyone contributes. I don't have time to author the changes but happy to review. |
toothrot
added
the
NeedsInvestigation
|
I would have a look on this issue. I will start with https://golang.org/pkg/path/filepath/#Walk and adapt the example with $GOROOT/src. |
|
a proposal to simplify Walk package main
import (
"fmt"
"os"
"path/filepath"
"syscall"
)
func walkFn(path string, info os.FileInfo, err error) error {
if err != nil {
fmt.Printf("*** prevent panic by handling failure accessing a path %q: %v ***\n", path, err)
return err
}
subDirToSkip := "zip"
if info.IsDir() && info.Name() == subDirToSkip {
fmt.Printf("*** skipping a DIR without errors: %+v ***\n", info.Name())
return filepath.SkipDir
}
subFileToSkip := "star.tar"
if info.Mode().IsRegular() && info.Name() == subFileToSkip {
fmt.Printf("*** skipping a FILE (and the remaining files in the containing directory) without errors: %+v ***\n", info.Name())
return filepath.SkipDir
}
fmt.Printf("visited file or dir: %q\n", path)
return nil
}
func main() {
gorootDir, found := syscall.Getenv ("GOROOT")
if (!found) {
fmt.Printf("GOROOT Env Variable not defined!\n")
return
}
tmpDir := gorootDir + "\\src\\archive"
err := filepath.Walk(tmpDir, walkFn)
if (err != nil) && (err != filepath.SkipDir) {
fmt.Printf("error walking the path %q: %v\n", tmpDir, err)
return
}
} |
|
Is this the kind of simplification for TeeReader you are expecting? package main
import (
"io"
"io/ioutil"
"os"
"strings"
)
func main() {
var r io.Reader = strings.NewReader("some io.Reader stream to be read\n")
// every byte read from 'r' will also be written to 'os.Stdout' before
r = io.TeeReader(r, os.Stdout)
// reading from it will also print to stdout now!
ioutil.ReadAll(r)
}If yes happy to start pushing CLs (first contrib here ;-) ) |
Now TeeReader example is simpler: - less dependencies - a frequent usage of a Tee - an piece of code that can be copy/pasted easily Updates golang#36417
- CopyN: 5 creates ambiguity with respect to whitespace and upperbound - TeeReader less boilerplate and displays a common usage of it - SectionReader_* all sections unified to 5:17 for clarity - SectionReader_Seek uses io.Copy to stdout like other examples - Seeker_Seek remove useless prints - Pipe print reader like other examples Updates golang#36417
- CopyN: 5 creates ambiguity with respect to whitespace and upperbound - TeeReader less boilerplate and displays a common usage of it - SectionReader_* all sections unified to 5:17 for clarity - SectionReader_Seek uses io.Copy to stdout like other examples - Seeker_Seek remove useless prints - Pipe print reader like other examples Updates golang#36417
|
Change https://golang.org/cl/227868 mentions this issue: |
- CopyN: 5 creates ambiguity with respect to whitespace and upperbound - TeeReader less boilerplate and displays a common usage of it - SectionReader_* all sections unified to 5:17 for clarity - SectionReader_Seek uses io.Copy to stdout like other examples - Seeker_Seek remove useless prints - Pipe print reader like other examples Updates #36417 Change-Id: Ibd01761d5a5786cdb1ea934f7a98f8302430c8a5 GitHub-Last-Rev: 4c17f9a GitHub-Pull-Request: #38379 Reviewed-on: https://go-review.googlesource.com/c/go/+/227868 Run-TryBot: Ian Lance Taylor <iant@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Ian Lance Taylor <iant@golang.org>
|
Not sure if I should open a separate issue but the example for StderrPipe is actually wrong because it deadlocks with the following output (just press "Run" in the linked documentation page): Let me know, I'd like to work on this as my first tiny contribution to this amazing community! |
|
@giannimassi You don't need to open an issue to send a fix. If you see a problem and you have a fix please go ahead and send it in as outlined at https://go.dev/doc/contribute. Thanks. |
Over the last few years, Go standard library has done a great job by improving the examples coverage. However, some of the examples are difficult to read or too comprehensive to be a reference for basic usage.
Standard library examples can help more if they were simpler and more copy/paste-able. More comprehensive scenarios can be covered as secondary examples or in other mediums such as https://gobyexample.com/.
Here are some examples:
It creates a directory, adds a lot of logic, prints out unix-specific comments, etc. Instead, it can demonstrate how to walk in a well known path, such as the home directory.
It doesn't really demonstrate a case where a TeeReader is useful. Running is required to understand what it does.
It is hard to follow what the sh is supposed to do with "echo stdout; echo 1>&2 stderr". It would be more valuable if the command is something everyone can relate.
Sorry for having to nitpick these examples, there are more cases in the standard library and it would be great to turn some of these examples into more digest ones.
Having said that, I see some packages (such as the io ones) might be better with comprehensive examples where edge cases are explained and demonstrable by running the example program because APIs are not always doing a great job explaining the behavior.
The text was updated successfully, but these errors were encountered: