Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

all: simplify standard library examples #36417

Open
rakyll opened this issue Jan 6, 2020 · 7 comments
Open

all: simplify standard library examples #36417

rakyll opened this issue Jan 6, 2020 · 7 comments

Comments

@rakyll
Copy link
Contributor

@rakyll rakyll commented Jan 6, 2020

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:

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.

@mvdan
Copy link
Member

@mvdan mvdan commented Jan 7, 2020

Instead, it can demonstrate how to walk in a well known path, such as the home directory.

One's home directory could be huge, though. How about $GOROOT/src? It contains ~7k entries, and I think it's a nice meta-example to show where the standard library lives.

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? :)

@rakyll
Copy link
Contributor Author

@rakyll rakyll commented Jan 7, 2020

How about $GOROOT/src?

We can discuss the details on CLs, I suggested an alternative just to explain my point :)

Will you be sending CLs as part of this issue, or is this a call for others to help? :)

I am hoping this becomes a placeholder issue and everyone contributes. I don't have time to author the changes but happy to review.

@agnivade
Copy link
Contributor

@agnivade agnivade commented Jan 9, 2020

@alain91
Copy link

@alain91 alain91 commented Feb 2, 2020

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.

@alain91
Copy link

@alain91 alain91 commented Feb 6, 2020

@rakyll

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
	}
    
}
@etnz
Copy link
Contributor

@etnz etnz commented Apr 10, 2020

@rakyll

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 ;-) )

etnz added a commit to etnz/go that referenced this issue Apr 11, 2020
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
etnz added a commit to etnz/go that referenced this issue Apr 11, 2020
- 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
etnz added a commit to etnz/go that referenced this issue Apr 11, 2020
- 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
@gopherbot
Copy link

@gopherbot gopherbot commented Apr 11, 2020

Change https://golang.org/cl/227868 mentions this issue: io: simplify Examples

gopherbot pushed a commit that referenced this issue Apr 13, 2020
- 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
7 participants
You can’t perform that action at this time.