code review 7220048: archive/tar: Add reader and writer code example.

archive/tar: Add reader and writer code example.

Remove the previous comment examples.

[u, 2013-01-26 16:26:57]

Hello golang-dev@googlegroups.com,

I'd like you to review this change to
https://code.google.com/p/go

[u, 2013-01-26 16:35:13]

Hello golang-dev@googlegroups.com (cc: golang-dev@googlegroups.com),

Please take another look.

[u, 2013-01-26 16:37:06]

Hello golang-dev@googlegroups.com (cc: golang-dev@googlegroups.com),

Please take another look.

[u, 2013-01-26 17:05:19]

First I added an example for tar.Writer as well, but removed it in favor of the
much more concise comment.

Pros:
* The concise example captures the important aspects without distractions.
Cons:
* It isn't checked for compile time errors since it's a comment.

For reader it makes sense to use a code example, since it will dual as a test
case.

Could we make a concise tar.Writer code example or should we stay with using the
comment example?

[minux1, 2013-01-26 19:01:23]

On Sun, Jan 27, 2013 at 1:05 AM, <r.eklind.87@gmail.com> wrote:

> First I added an example for tar.Writer as well, but removed it in favor
> of the much more concise comment.
>
> Pros:
> * The concise example captures the important aspects without
> distractions.
> Cons:
> * It isn't checked for compile time errors since it's a comment.
>
> For reader it makes sense to use a code example, since it will dual as a
> test case.
>
> Could we make a concise tar.Writer code example or should we stay with
> using the comment example?
>
my opinion is that if we can integrate the comments in the example comment
into the example code, we can get rid of the example comments.

[adg, 2013-01-29 04:21:48]

https://codereview.appspot.com/7220048/diff/1002/src/pkg/archive/tar/example_...
File src/pkg/archive/tar/example_test.go (right):

https://codereview.appspot.com/7220048/diff/1002/src/pkg/archive/tar/example_...
src/pkg/archive/tar/example_test.go:11: func ExampleReader() {
We could make this example self-contained by covering both the reader and the
writer parts. First write a tar file into a bytes.Buffer and then read it back.

What do you think?

[u, 2013-01-31 03:10:33]

Hello golang-dev@googlegroups.com, minux.ma@gmail.com, adg@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[u, 2013-01-31 03:15:17]

Hello golang-dev@googlegroups.com, minux.ma@gmail.com, adg@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[u, 2013-01-31 03:17:41]

On 2013/01/29 04:21:48, adg wrote:
>
https://codereview.appspot.com/7220048/diff/1002/src/pkg/archive/tar/example_...
> File src/pkg/archive/tar/example_test.go (right):
> 
>
https://codereview.appspot.com/7220048/diff/1002/src/pkg/archive/tar/example_...
> src/pkg/archive/tar/example_test.go:11: func ExampleReader() {
> We could make this example self-contained by covering both the reader and the
> writer parts. First write a tar file into a bytes.Buffer and then read it
back.
> 
> What do you think?

Sounds good and sorry for the double commit. Any suggestions of how to make it
cleaner?

[adg, 2013-01-31 04:46:46]

Actually I was thinking that we should avoid relying on testdata/ files
altogether, so that this can be run in the playground sandbox.

[minux1, 2013-01-31 08:34:16]

On Thursday, January 31, 2013, Andrew Gerrand wrote:

> Actually I was thinking that we should avoid relying on testdata/ files
> altogether, so that this can be run in the playground sandbox.
>
i imagine that when running locally with godoc -play,
we can start the compiled binary under the directory
for the current package, so that examples using
testdat could be run, what do you think?

[u, 2013-01-31 16:32:05]

Hello golang-dev@googlegroups.com, minux.ma@gmail.com, adg@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[u, 2013-01-31 16:33:39]

On 2013/01/31 16:32:05, u wrote:
> Hello mailto:golang-dev@googlegroups.com, mailto:minux.ma@gmail.com,
mailto:adg@golang.org (cc:
> mailto:golang-dev@googlegroups.com),
> 
> Please take another look.

I agree that it's nice if this code runs smoothly in the playground. The only
thing missing would be the example usage of tar.FileInfoHeader, which is quite
convenient when handling actual files.

I've updated the example code. Before the final commit, "hello world" could be
replaced with something more imaginative.

[u, 2013-01-31 16:51:08]

Hello golang-dev@googlegroups.com, minux.ma@gmail.com, adg@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[u, 2013-01-31 16:53:05]

The examples are now more consistent with the zip examples.

The zip example is split into a reader and a writer. The reader uses testdata.
What is the preferred solution?

[adg, 2013-01-31 23:55:05]

https://codereview.appspot.com/7220048/diff/8008/src/pkg/archive/tar/example_...
File src/pkg/archive/tar/example_test.go (right):

https://codereview.appspot.com/7220048/diff/8008/src/pkg/archive/tar/example_...
src/pkg/archive/tar/example_test.go:28: hdr := new(tar.Header)
hdr := &tar.Header{
  Name: file.Name,
  Size: int64(len(file.Body)),
}

https://codereview.appspot.com/7220048/diff/8008/src/pkg/archive/tar/example_...
src/pkg/archive/tar/example_test.go:30: // populate other hdr fields as desired.
delete this, kinda obvious

https://codereview.appspot.com/7220048/diff/8008/src/pkg/archive/tar/example_...
src/pkg/archive/tar/example_test.go:47: // Iterate through the files in the
archive.
add a blank line above this

https://codereview.appspot.com/7220048/diff/8008/src/pkg/archive/tar/example_...
src/pkg/archive/tar/example_test.go:74: // Write more examples.
delete this line :-) I love the rest

[u, 2013-02-01 06:05:15]

Hello golang-dev@googlegroups.com, minux.ma@gmail.com, adg@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[adg, 2013-02-04 01:35:18]

LGTM

[adg, 2013-02-04 01:37:27]

*** Submitted as https://code.google.com/p/go/source/detail?r=a8d940d69a3e ***

archive/tar: Add reader and writer code example.

Remove the previous comment examples.

R=golang-dev, minux.ma, adg
CC=golang-dev
https://codereview.appspot.com/7220048

Committer: Andrew Gerrand <adg@golang.org>

[mikio, 2013-02-04 03:26:24]

https://codereview.appspot.com/7220048/diff/19001/src/pkg/archive/tar/example...
File src/pkg/archive/tar/example_test.go (right):

https://codereview.appspot.com/7220048/diff/19001/src/pkg/archive/tar/example...
src/pkg/archive/tar/example_test.go:1: package tar_test
copyright?

[u, 2013-02-22 08:11:12]

*** Abandoned ***