Tweak doc comments.

java/src/main/java/com/google/protobuf/RpcCallback.java

@@ -34,6 +34,12 @@ package com.google.protobuf;
  * Interface for an RPC callback, normally called when an RPC completes.
  * {@code ParameterType} is normally the method's response message type.
  *
+ * <p>Starting with version 2.3.0, RPC implementations should not try to build
+ * on this, but should instead provide code generator plugins which generate
+ * code specific to the particular RPC implementation.  This way the generated
+ * code can be more appropriate for the implementation in use and can avoid
+ * unnecessary layers of indirection.
+ *
  * @author kenton@google.com Kenton Varda
  */
 public interface RpcCallback<ParameterType> {

java/src/main/java/com/google/protobuf/RpcChannel.java

@@ -44,6 +44,12 @@ package com.google.protobuf;
  *   service.myMethod(controller, request, callback);
  * </pre>
  *
+ * <p>Starting with version 2.3.0, RPC implementations should not try to build
+ * on this, but should instead provide code generator plugins which generate
+ * code specific to the particular RPC implementation.  This way the generated
+ * code can be more appropriate for the implementation in use and can avoid
+ * unnecessary layers of indirection.
+ *
  * @author kenton@google.com Kenton Varda
  */
 public interface RpcChannel {

java/src/main/java/com/google/protobuf/RpcController.java

@@ -35,6 +35,12 @@ package com.google.protobuf;
  * purpose of the controller is to provide a way to manipulate settings
  * specific to the RPC implementation and to find out about RPC-level errors.
  *
+ * <p>Starting with version 2.3.0, RPC implementations should not try to build
+ * on this, but should instead provide code generator plugins which generate
+ * code specific to the particular RPC implementation.  This way the generated
+ * code can be more appropriate for the implementation in use and can avoid
+ * unnecessary layers of indirection.
+ *
  * <p>The methods provided by the {@code RpcController} interface are intended
  * to be a "least common denominator" set of features which we expect all
  * implementations to support.  Specific implementations may provide more

java/src/main/java/com/google/protobuf/Service.java

@@ -37,6 +37,12 @@ package com.google.protobuf;
  * interface can be used to call the methods of the service without knowing
  * its exact type at compile time (analogous to the Message interface).
  *
+ * <p>Starting with version 2.3.0, RPC implementations should not try to build
+ * on this, but should instead provide code generator plugins which generate
+ * code specific to the particular RPC implementation.  This way the generated
+ * code can be more appropriate for the implementation in use and can avoid
+ * unnecessary layers of indirection.
+ *
  * @author kenton@google.com Kenton Varda
  */
 public interface Service {

python/google/protobuf/service.py

@@ -28,12 +28,16 @@
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-"""Declares the RPC service interfaces.
+"""DEPRECATED:  Declares the RPC service interfaces.
 
 This module declares the abstract interfaces underlying proto2 RPC
 services.  These are intended to be independent of any particular RPC
 implementation, so that proto2 services can be used on top of a variety
-of implementations.
+of implementations.  Starting with version 2.3.0, RPC implementations should
+not try to build on these, but should instead provide code generator plugins
+which generate code specific to the particular RPC implementation.  This way
+the generated code can be more appropriate for the implementation in use
+and can avoid unnecessary layers of indirection.
 """
 
 __author__ = 'petar@google.com (Petar Petrov)'

src/google/protobuf/compiler/code_generator.h

@@ -98,15 +98,15 @@ class LIBPROTOC_EXPORT OutputDirectory {
   //
   // The filename given should be relative to the root of the source tree.
   // E.g. the C++ generator, when generating code for "foo/bar.proto", will
-  // generate the files "foo/bar.pb2.h" and "foo/bar.pb2.cc"; note that
+  // generate the files "foo/bar.pb.h" and "foo/bar.pb.cc"; note that
   // "foo/" is included in these filenames.  The filename is not allowed to
   // contain "." or ".." components.
   virtual io::ZeroCopyOutputStream* Open(const string& filename) = 0;
 
   // Creates a ZeroCopyOutputStream which will insert code into the given file
-  // at the given insertion point.  See plugin.proto for more information on
-  // insertion points.  The default implementation assert-fails -- it exists
-  // only for backwards-compatibility.
+  // at the given insertion point.  See plugin.proto (plugin.pb.h) for more
+  // information on insertion points.  The default implementation
+  // assert-fails -- it exists only for backwards-compatibility.
   //
   // WARNING:  This feature is currently EXPERIMENTAL and is subject to change.
   virtual io::ZeroCopyOutputStream* OpenForInsert(

src/google/protobuf/compiler/plugin.h

@@ -29,6 +29,28 @@
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 // Author: kenton@google.com (Kenton Varda)
+//
+// Front-end for protoc code generator plugins written in C++.
+//
+// To implement a protoc plugin in C++, simply write an implementation of
+// CodeGenerator, then create a main() function like:
+//   int main(int argc, char* argv[]) {
+//     MyCodeGenerator generator;
+//     return google::protobuf::compiler::PluginMain(argc, argv, &generator);
+//   }
+// You must link your plugin against libprotobuf and libprotoc.
+//
+// To get protoc to use the plugin, do one of the following:
+// * Place the plugin binary somewhere in the PATH and give it the name
+//   "protoc-gen-NAME" (replacing "NAME" with the name of your plugin).  If you
+//   then invoke protoc with the parameter --NAME_out=OUT_DIR (again, replace
+//   "NAME" with your plugin's name), protoc will invoke your plugin to generate
+//   the output, which will be placed in OUT_DIR.
+// * Place the plugin binary anywhere, with any name, and pass the --plugin
+//   parameter to protoc to direct it to your plugin like so:
+//     protoc --plugin=protoc-gen-NAME=path/to/mybinary --NAME_out=OUT_DIR
+//   On Windows, make sure to include the .exe suffix:
+//     protoc --plugin=protoc-gen-NAME=path/to/mybinary.exe --NAME_out=OUT_DIR
 
 #ifndef GOOGLE_PROTOBUF_COMPILER_PLUGIN_H__
 #define GOOGLE_PROTOBUF_COMPILER_PLUGIN_H__
@@ -41,12 +63,7 @@ namespace compiler {
 
 class CodeGenerator;    // code_generator.h
 
-// To implement a protoc plugin in C++, simply write an implementation of
-// CodeGenerator, then create a main() function like:
-//   int main(int argc, char* argv[]) {
-//     MyCodeGenerator generator;
-//     return PluginMain(argc, argv, &generator);
-//   }
+// Implements main() for a protoc plugin exposing the given code generator.
 LIBPROTOC_EXPORT int PluginMain(int argc, char* argv[], const CodeGenerator* generator);
 
 }  // namespace compiler

src/google/protobuf/compiler/plugin.proto

@@ -117,10 +117,10 @@ message CodeGeneratorResponse {
     //
     // For example, the C++ code generator places the following line in the
     // .pb.h files that it generates:
-    //   // @@protoc_insertion_point(package_level_decls)
+    //   // @@protoc_insertion_point(namespace_scope)
     // This line appears within the scope of the file's package namespace, but
     // outside of any particular class.  Another plugin can then specify the
-    // insertion_point "package_level_decls" to generate additional classes or
+    // insertion_point "namespace_scope" to generate additional classes or
     // other declarations that should be placed in this scope.
     //
     // Note that if the line containing the insertion point begins with
@@ -130,6 +130,11 @@ message CodeGeneratorResponse {
     // should be indented the same amount as any inserted code will need to be
     // in order to work correctly in that context.
     //
+    // The code generator that generates the initial file and the one which
+    // inserts into it must both run as part of a single invocatino of protoc.
+    // Code generators are executed in the order in which they appear on the
+    // command line.
+    //
     // If |insertion_point| is present, |name| must also be present.
     optional string insertion_point = 2;
 

src/google/protobuf/service.h

@@ -32,10 +32,14 @@
 //  Based on original Protocol Buffers design by
 //  Sanjay Ghemawat, Jeff Dean, and others.
 //
-// This module declares the abstract interfaces underlying proto2 RPC
-// services.  These are intented to be independent of any particular RPC
+// DEPRECATED:  This module declares the abstract interfaces underlying proto2
+// RPC services.  These are intented to be independent of any particular RPC
 // implementation, so that proto2 services can be used on top of a variety
-// of implementations.
+// of implementations.  Starting with version 2.3.0, RPC implementations should
+// not try to build on these, but should instead provide code generator plugins
+// which generate code specific to the particular RPC implementation.  This way
+// the generated code can be more appropriate for the implementation in use
+// and can avoid unnecessary layers of indirection.
 //
 //
 // When you use the protocol compiler to compile a service definition, it