diff --git a/src/pkg/os/file.go b/src/pkg/os/file.go
index 439164241affc8d4879f00fc2730d1e2be8074e2..ddcaa6fed9fb63c4bc2099bfee17c3e49cbb815d 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 (