diff options
author | kenton@google.com <kenton@google.com@630680e5-0e50-0410-840e-4b1c322b438d> | 2010-01-08 03:56:03 +0000 |
---|---|---|
committer | kenton@google.com <kenton@google.com@630680e5-0e50-0410-840e-4b1c322b438d> | 2010-01-08 03:56:03 +0000 |
commit | 7b7a80eae4f46cca5d3a2781b4412ef769856cdb (patch) | |
tree | 21e30be605eec4eaac32653e692ba7f1aedee9c6 /src | |
parent | 83aba29ebee2bb0885ab2db04b3ad6b22463fe58 (diff) | |
download | protobuf-7b7a80eae4f46cca5d3a2781b4412ef769856cdb.tar.gz protobuf-7b7a80eae4f46cca5d3a2781b4412ef769856cdb.tar.bz2 protobuf-7b7a80eae4f46cca5d3a2781b4412ef769856cdb.zip |
Tweak doc comments.
Diffstat (limited to 'src')
-rw-r--r-- | src/google/protobuf/compiler/code_generator.h | 8 | ||||
-rw-r--r-- | src/google/protobuf/compiler/plugin.h | 29 | ||||
-rw-r--r-- | src/google/protobuf/compiler/plugin.proto | 9 | ||||
-rw-r--r-- | src/google/protobuf/service.h | 10 |
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 |