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.

Sign up for GitHub

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

Jump to bottom

compress/gzip: suggestions for doc improvements #11398

Closed
brunetto opened this issue Jun 25, 2015 · 3 comments
Closed

compress/gzip: suggestions for doc improvements #11398

brunetto opened this issue Jun 25, 2015 · 3 comments
Labels
FrozenDueToAge

Comments

@brunetto
Copy link

Submit here having read the docs thread on the ML.

Reading (for example) the doc about NewWriter it is not clear nor trivial to understand how gzip.NewWriter could interact with (for example) bufio.NewWriter. I found this gist that helped me in understanding the right order.
May be an example like

package main

import (
    "bufio"
    "compress/gzip"
    "log"
    "os"
)

func main() {
    file, err := os.Create("File.gz")
    if err != nil {
        log.Fatal(err)
    }
    defer file.Close()

    gzipWriter := gzip.NewWriter(file)
    defer gzipWriter.Close()
    defer gzipWriter.Flush()

    writer := bufio.NewWriter(gzipWriter)
    defer writer.Flush()

    writer.WriteString("gzipWriter.go created this file.\n")
}

can help.
@adg
Copy link
Contributor

adg commented Jun 26, 2015

But that's the wrong order (buffer -> gzip -> file). You typically want to buffer writes to the file (gzip -> buffer -> file), not writes to the gzip compressor (it doesn't care how big or small your writes are). Also you shouldn't ignore the errors from Flush and Close.

What I'm saying is: I agree this should be better documented. I don't think compress/gzip is the right place to do it, though.

I think we should add a solid section to the tour about working with the io interfaces. Or even a blog post would do.

@adg
Copy link
Contributor

adg commented Jun 26, 2015

This is a dupe of #11373

@adg adg closed this as completed Jun 26, 2015
@brunetto
Copy link
Author

Yes, I missed the errors!! Ops!!
But what is the best way to check for the errors with defer???

I thought gzip was like a filter, compressing whatever bufio.Writer passes when it does it.
Like an extra layer between the writer and the file object compressing the data. It seems I was wrong, but how can I deal with an application that can write both normal and compressed files depending on the input? If gzip.Writer sits on top of bufio, I need to change the writer I pass to the function that actually writes when I change the output file type. Or not?

Regarding the docs, my opinion is that some examples should be written both in a tutorial (blog/tour) and in the docs (maybe something shorted/simpler). But this is only my opinion. At least, maybe a link to the tutorial placed in the docs page would help.

@golang golang locked and limited conversation to collaborators Jun 25, 2016
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@brunetto @adg @gopherbot