Tweak doc comments.

4 files changed, 41 insertions, 15 deletions

diff --git a/src/google/protobuf/compiler/code_generator.h b/src/google/protobuf/compiler/code_generator.h
index 7dffe04e..ea094cdd 100644
--- a/src/google/protobuf/compiler/code_generator.h
+++ b/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(
diff --git a/src/google/protobuf/compiler/plugin.h b/src/google/protobuf/compiler/plugin.h
index 4731b47b..7c403332 100644
--- a/src/google/protobuf/compiler/plugin.h
+++ b/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
diff --git a/src/google/protobuf/compiler/plugin.proto b/src/google/protobuf/compiler/plugin.proto
index d91c06e4..4e928b0d 100644
--- a/src/google/protobuf/compiler/plugin.proto
+++ b/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;
 
diff --git a/src/google/protobuf/service.h b/src/google/protobuf/service.h
index 83f5f38d..a6a7d16d 100644
--- a/src/google/protobuf/service.h
+++ b/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