goprotobuf: Generate package docs.

Most people won't see these, but they improve how proto packages are rendered by godoc.

R=r
CC=golang-codereviews
https://codereview.appspot.com/51030043

proto/testdata/test.pb.go

@@ -2,6 +2,38 @@
 // source: test.proto
 // DO NOT EDIT!
 
+/*
+Package testdata is a generated protocol buffer package.
+
+It is generated from these files:
+	test.proto
+
+It has these top-level messages:
+	GoEnum
+	GoTestField
+	GoTest
+	GoSkipTest
+	NonPackedTest
+	PackedTest
+	MaxTag
+	OldMessage
+	NewMessage
+	InnerMessage
+	OtherMessage
+	MyMessage
+	Ext
+	MyMessageSet
+	Empty
+	MessageList
+	Strings
+	Defaults
+	SubDefaults
+	RepeatedEnum
+	MoreRepeated
+	GroupOld
+	GroupNew
+	FloatingPoint
+*/
 package testdata
 
 import proto "code.google.com/p/goprotobuf/proto"

protoc-gen-go/descriptor/descriptor.pb.go

@@ -2,6 +2,31 @@
 // source: google/protobuf/descriptor.proto
 // DO NOT EDIT!
 
+/*
+Package google_protobuf is a generated protocol buffer package.
+
+It is generated from these files:
+	google/protobuf/descriptor.proto
+
+It has these top-level messages:
+	FileDescriptorSet
+	FileDescriptorProto
+	DescriptorProto
+	FieldDescriptorProto
+	EnumDescriptorProto
+	EnumValueDescriptorProto
+	ServiceDescriptorProto
+	MethodDescriptorProto
+	FileOptions
+	MessageOptions
+	FieldOptions
+	EnumOptions
+	EnumValueOptions
+	ServiceOptions
+	MethodOptions
+	UninterpretedOption
+	SourceCodeInfo
+*/
 package google_protobuf
 
 import proto "code.google.com/p/goprotobuf/proto"

protoc-gen-go/generator/generator.go

@@ -239,6 +239,8 @@ type FileDescriptor struct {
 	// as a map from the exported object to its symbols.
 	// This is used for supporting public imports.
 	exported map[Object][]symbol
+
+	index int // The index of this file in the list of files to generate code for
 }
 
 // PackageName is the package name we'll use in the generated code to refer to this file.
@@ -673,6 +675,7 @@ FindFiles:
 		for _, file := range g.allFiles {
 			if fileName == file.GetName() {
 				g.genFiles[i] = file
+				file.index = i
 				continue FindFiles
 			}
 		}
@@ -1028,10 +1031,33 @@ func (g *Generator) generate(file *FileDescriptor) {
 // Generate the header, including package definition
 func (g *Generator) generateHeader() {
 	g.P("// Code generated by protoc-gen-go.")
-	g.P("// source: ", *g.file.Name)
+	g.P("// source: ", g.file.Name)
 	g.P("// DO NOT EDIT!")
 	g.P()
-	g.P("package ", g.file.PackageName())
+
+	name := g.file.PackageName()
+
+	if g.file.index == 0 {
+		// Generate package docs for the first file in the package.
+		g.P("/*")
+		g.P("Package ", name, " is a generated protocol buffer package.")
+		g.P()
+		g.P("It is generated from these files:")
+		for _, f := range g.genFiles {
+			g.P("\t", f.Name)
+		}
+		g.P()
+		g.P("It has these top-level messages:")
+		for _, msg := range g.file.desc {
+			if msg.parent != nil {
+				continue
+			}
+			g.P("\t", CamelCaseSlice(msg.TypeName()))
+		}
+		g.P("*/")
+	}
+
+	g.P("package ", name)
 	g.P()
 }
 

protoc-gen-go/plugin/plugin.pb.go

@@ -2,6 +2,16 @@
 // source: google/protobuf/compiler/plugin.proto
 // DO NOT EDIT!
 
+/*
+Package google_protobuf_compiler is a generated protocol buffer package.
+
+It is generated from these files:
+	google/protobuf/compiler/plugin.proto
+
+It has these top-level messages:
+	CodeGeneratorRequest
+	CodeGeneratorResponse
+*/
 package google_protobuf_compiler
 
 import proto "code.google.com/p/goprotobuf/proto"

protoc-gen-go/testdata/my_test/test.pb.go

@@ -2,6 +2,18 @@
 // source: my_test/test.proto
 // DO NOT EDIT!
 
+/*
+Package my_test is a generated protocol buffer package.
+
+It is generated from these files:
+	my_test/test.proto
+
+It has these top-level messages:
+	Request
+	Reply
+	ReplyExtensions
+	OldReply
+*/
 package my_test
 
 import proto "code.google.com/p/goprotobuf/proto"

protoc-gen-go/testdata/my_test/test.pb.go.golden

@@ -2,6 +2,18 @@
 // source: my_test/test.proto
 // DO NOT EDIT!
 
+/*
+Package my_test is a generated protocol buffer package.
+
+It is generated from these files:
+	my_test/test.proto
+
+It has these top-level messages:
+	Request
+	Reply
+	ReplyExtensions
+	OldReply
+*/
 package my_test
 
 import proto "code.google.com/p/goprotobuf/proto"