update go docs

desc/doc.go

@@ -24,18 +24,42 @@
 // properties that are not immediately accessible through rich descriptor's
 // methods.
 //
+// Also see the grpcreflect, dynamic, and grpcdynamic packages in this same
+// repo to see just how useful rich descriptors really are.
+//
+//
+// Loading Descriptors
+//
 // Rich descriptors can be accessed in similar ways as their "poor" cousins
 // (descriptor protos). Instead of using proto.FileDescriptor, use
 // desc.LoadFileDescriptor. Message descriptors and extension field descriptors
 // can also be easily accessed using desc.LoadMessageDescriptor and
 // desc.LoadFieldDescriptorForExtension, respectively.
 //
+// If you are using the protoc-gen-gosrcinfo plugin (also in this repo), then
+// the descriptors returned from these Load* functions will include source code
+// information, and thus include comments for elements.
+//
+//
+// Creating Descriptors
+//
 // It is also possible create rich descriptors for proto messages that a given
 // Go program doesn't even know about. For example, they could be loaded from a
 // FileDescriptorSet file (which can be generated by protoc) or loaded from a
 // server. This enables interesting things like dynamic clients: where a Go
 // program can be an RPC client of a service it wasn't compiled to know about.
 //
-// Also see the grpcreflect, dynamic, and grpcdynamic packages in this same
-// repo to see just how useful rich descriptors really are.
+// You cannot create a message descriptor without also creating its enclosing
+// file, because the enclosing file is what contains other relevant information
+// like other symbols and dependencies/imports, which is how type references
+// are resolved (such as when a field in a message has a type that is another
+// message or enum).
+//
+// So the functions in this package for creating descriptors are all for
+// creating *file* descriptors. See the various Create* functions for more
+// information.
+//
+// Also see the desc/builder sub-package, for another API that makes it easier
+// to synthesize descriptors programmatically.
+//
 package desc

desc/sourceinfo/registry.go

@@ -10,8 +10,22 @@
 // But the presence of comments, and the ability to show them to humans, can greatly
 // improve the utility of user agents that use the reflection service.
 //
-// So, by using the protoc-gen-gosrcinfo plugin and this package, we can recover the
-// source code info and comments that were otherwise stripped by protoc-gen-go.
+// When the protoc-gen-gosrcinfo plugin is used, the desc.Load* methods, which load
+// descriptors for compiled-in elements, will automatically include source code
+// info, using the data registered with this package.
+//
+// In order to make the reflection service use this functionality, you will need to
+// be using v1.45 or higher of the Go runtime for gRPC (google.golang.org/grpc). The
+// following snippet demonstrates how to do this in your server. Do this instead of
+// using the reflection.Register function:
+//
+//    refSvr := reflection.NewServer(reflection.ServerOptions{
+//        Services:           grpcServer,
+//        DescriptorResolver: sourceinfo.GlobalFiles,
+//        ExtensionResolver:  sourceinfo.GlobalFiles,
+//    })
+//    grpc_reflection_v1alpha.RegisterServerReflectionServer(grpcServer, refSvr)
+//
 package sourceinfo
 
 import (