From: Rob Pike <r@golang.org>
Date: Fri, 17 Feb 2012 03:30:25 +0000 (+1100)
Subject: os: add a simple example to the package doc.
X-Git-Tag: weekly.2012-02-22~169
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=efb28b2ac1808bcbb7df28d12addc6df630353d5;p=gostls13.git

os: add a simple example to the package doc.
Shows error handling and slices for Read and Write.

R=golang-dev, rsc
CC=golang-dev
https://golang.org/cl/5676075
---

diff --git a/src/pkg/os/file.go b/src/pkg/os/file.go
index 439164241a..ddcaa6fed9 100644
--- a/src/pkg/os/file.go
+++ b/src/pkg/os/file.go
@@ -7,11 +7,33 @@
 // Go-like; failing calls return values of type error rather than error numbers.
 // Often, more information is available within the error. For example,
 // if a call that takes a file name fails, such as Open or Stat, the error
-// will include failing file name when printed and will be of type *PathError,
-// which may be unpacked for more information.
+// will include the failing file name when printed and will be of type
+// *PathError, which may be unpacked for more information.
 // 
 // The os interface is intended to be uniform across all operating systems.
 // Features not generally available appear in the system-specific package syscall.
+//
+// Here is a simple example, opening a file and reading some of it.
+//
+//	file, err := os.Open("file.go") // For read access.
+//	if err != nil {
+//		log.Fatal(err)
+//	}
+//
+// If the open fails, the error string will be self-explanatory, like
+//
+//	open file.go: no such file or directory
+//
+// The file's data can then be read into a slice of bytes. Read and
+// Write take their byte counts from the length of the artument slice.
+//
+//	data := make([]byte, 100)
+//	count, err := file.Read(data)
+//	if err != nil {
+//		log.Fatal(err)
+//	}
+//	fmt.Printf("read %d bytes: %q\n", count, data[:count])
+//
 package os
 
 import (