Add warning note to RegisterXXXHandlerServer (#1399)

* deprecate Regiter_XXX_HandlerServer

* use Register_XXX_FromEndpoint instead

* fix deprecated description and tests

* fix verbal

* fix tests

* change wording

Author: joesonw

examples/internal/helloworld/helloworld.pb.gw.go

@@ -564,6 +564,7 @@ func local_request_{{.Method.Service.GetName}}_{{.Method.GetName}}_{{.Index}}(ct
 // Register{{$svc.GetName}}{{$.RegisterFuncSuffix}}Server registers the http handlers for service {{$svc.GetName}} to "mux".
 // UnaryRPC     :call {{$svc.GetName}}Server directly.
 // StreamingRPC :currently unsupported pending https://github.com/grpc/grpc-go/issues/906.
+// Note that using this registration option will cause many gRPC library features (such as grpc.SendHeader, etc) to stop working. Consider using Register{{$svc.GetName}}{{$.RegisterFuncSuffix}}FromEndpoint instead.
 func Register{{$svc.GetName}}{{$.RegisterFuncSuffix}}Server(ctx context.Context, mux *runtime.ServeMux, server {{$svc.GetName}}Server) error {
 	{{range $m := $svc.Methods}}
 	{{range $b := $m.Bindings}}

examples/internal/proto/examplepb/a_bit_of_everything.pb.gw.go

@@ -28,7 +28,7 @@ message Swagger {
   // it is not included, the API is served directly under the host. The value 
   // MUST start with a leading slash (/). The basePath does not support path
   // templating.
-  // Note that using `base_path` does not change the endpoint paths that are 
+  // Note that using this registration option will cause many gRPC library features (such as grpc.SendHeader, etc) to stop working. Consider using `base_path` does not change the endpoint paths that are 
   // generated in the resulting Swagger file. If you wish to use `base_path`
   // with relatively generated Swagger paths, the `base_path` prefix must be 
   // manually removed from your `google.api.http` paths and your code changed to