add top-level package comments for net, reflect, malloc.

reflect is a little more detailed than some because it affords an opportunity
to explain how to approach the library.

R=gri, rsc
CC=go-dev
http://go/go-review/1026026

diff --git a/src/pkg/malloc/malloc.go b/src/pkg/malloc/malloc.go
index 838b92f5f26c3b39a245c214c64c9209efbede3b..66708a680eb660f89c8b0db8f85682210f542887 100644 (file)
--- a/src/pkg/malloc/malloc.go
+++ b/src/pkg/malloc/malloc.go
@@ -6,6 +6,9 @@
 // The actual functions are written in C
 // and part of the runtime library.
 
+// The malloc package exposes statistics and other low-level details about
+// the run-time memory allocator and collector.  It is intended for debugging
+// purposes only; other uses are discouraged.
 package malloc
 
 type Stats struct {

diff --git a/src/pkg/net/net.go b/src/pkg/net/net.go
index d649756ed515a6bee2de3e3e69a39acd215c2b41..cc5e27ea043661ae6ea60dbf6a4a0a6344ac384c 100644 (file)
--- a/src/pkg/net/net.go
+++ b/src/pkg/net/net.go
@@ -2,6 +2,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// The net package provides a portable interface to Unix
+// networks sockets, including TCP/IP, UDP, domain name
+// resolution, and Unix domain sockets.
 package net
 
 // TODO(rsc):

diff --git a/src/pkg/reflect/type.go b/src/pkg/reflect/type.go
index 02eb549e8d2b6d3e31b4ddb311e27124c36fc431..e14892d5802c68aa3de561098c363c6288e97d8d 100644 (file)
--- a/src/pkg/reflect/type.go
+++ b/src/pkg/reflect/type.go
@@ -2,6 +2,17 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// The reflect package implements run-time reflection, allowing a program to
+// manipulate objects with arbitrary types.  The typical use is to take a
+// value with static type interface{} and extract its dynamic type
+// information by calling Typeof(), which returns an object with interface
+// type Type.  That contains a pointer to a struct of type *StructType,
+// *IntType, etc. representing the details of the underlying type.  A type
+// switch or type assertion can reveal which.
+//
+// A call to NewValue creates a Value representing the run-time data; it
+// contains a *StructValue, *IntValue, etc.  MakeZero takes a Type and
+// returns a Value representing a zero value for that type.
 package reflect
 
 import (