pic: document package

Effective Go¹ says every package should have a package comment,
and every exported name in a package should have a doc comment.

This package is mentioned in the Go tour. Let's set a good example.

¹ https://golang.org/doc/effective_go.html#commentary

Change-Id: Iac561c7530fc49d5ff17c51d925151ec8319ef24
Reviewed-on: https://go-review.googlesource.com/c/tour/+/232865
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Alexander Rakoczy <alex@golang.org>

1 files changed, 15 insertions, 2 deletions

diff --git a/pic/pic.go b/pic/pic.go
index 21edae7..7f22edd 100644
--- a/pic/pic.go
+++ b/pic/pic.go
@@ -1,7 +1,9 @@
-// Copyright 2011 The Go Authors.  All rights reserved.
+// Copyright 2011 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Package pic implements functions that
+// display pictures on the Go playground.
 package pic // import "golang.org/x/tour/pic"
 
 import (
@@ -12,7 +14,16 @@ import (
 	"image/png"
 )
 
-func Show(f func(int, int) [][]uint8) {
+// Show displays a picture defined by the function f
+// when executed on the Go Playground.
+//
+// f should return a slice of length dy,
+// each element of which is a slice of dx
+// 8-bit unsigned int. The integers are
+// interpreted as bluescale values,
+// where the value 0 means full blue,
+// and the value 255 means full white.
+func Show(f func(dx, dy int) [][]uint8) {
 	const (
 		dx = 256
 		dy = 256
@@ -32,6 +43,8 @@ func Show(f func(int, int) [][]uint8) {
 	ShowImage(m)
 }
 
+// ShowImage displays the image m
+// when executed on the Go Playground.
 func ShowImage(m image.Image) {
 	var buf bytes.Buffer
 	err := png.Encode(&buf, m)