From 3916a0aa999df3da9e8853b5911a5caf43a863fb Mon Sep 17 00:00:00 2001 From: Jisi Liu Date: Mon, 1 Aug 2016 18:47:45 -0700 Subject: Add and fix C++ runtime docs --- src/Makefile.am | 1 + src/google/protobuf/arena.h | 10 ++--- .../protobuf/compiler/command_line_interface.h | 5 +++ .../protobuf/compiler/csharp/csharp_generator.h | 6 +++ src/google/protobuf/compiler/js/js_generator.h | 6 +++ .../compiler/objectivec/objectivec_generator.h | 4 ++ .../compiler/objectivec/objectivec_helpers.h | 2 + src/google/protobuf/compiler/ruby/ruby_generator.h | 6 +++ src/google/protobuf/map.h | 9 +++-- src/google/protobuf/util/field_comparator.h | 2 + src/google/protobuf/util/field_mask_util.h | 2 + src/google/protobuf/util/package_info.h | 46 ++++++++++++++++++++++ src/google/protobuf/util/time_util.h | 3 ++ src/google/protobuf/util/type_resolver.h | 2 + src/google/protobuf/util/type_resolver_util.h | 2 + 15 files changed, 98 insertions(+), 8 deletions(-) create mode 100644 src/google/protobuf/util/package_info.h (limited to 'src') diff --git a/src/Makefile.am b/src/Makefile.am index 524886ea..cf3f1d8e 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -546,6 +546,7 @@ EXTRA_DIST = \ google/protobuf/testdata/text_format_unittest_extensions_data_pointy.txt \ google/protobuf/package_info.h \ google/protobuf/io/package_info.h \ + google/protobuf/util/package_info.h \ google/protobuf/compiler/ruby/ruby_generated_code.proto \ google/protobuf/compiler/ruby/ruby_generated_code_pb.rb \ google/protobuf/compiler/package_info.h \ diff --git a/src/google/protobuf/arena.h b/src/google/protobuf/arena.h index 58b1e126..0a5eacee 100644 --- a/src/google/protobuf/arena.h +++ b/src/google/protobuf/arena.h @@ -28,6 +28,8 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// This file defines an Arena allocator for better allocation performance. + #ifndef GOOGLE_PROTOBUF_ARENA_H__ #define GOOGLE_PROTOBUF_ARENA_H__ @@ -211,12 +213,10 @@ struct ArenaOptions { // // This protocol is implemented by all arena-enabled proto2 message classes as // well as RepeatedPtrField. - -#if __cplusplus >= 201103L -class LIBPROTOBUF_EXPORT Arena final { -#else +// +// Do NOT subclass Arena. This class will be marked as final when C++11 is +// enabled. class LIBPROTOBUF_EXPORT Arena { -#endif public: // Arena constructor taking custom options. See ArenaOptions below for // descriptions of the options available. diff --git a/src/google/protobuf/compiler/command_line_interface.h b/src/google/protobuf/compiler/command_line_interface.h index d1377666..32084567 100644 --- a/src/google/protobuf/compiler/command_line_interface.h +++ b/src/google/protobuf/compiler/command_line_interface.h @@ -55,6 +55,11 @@ class FileDescriptor; // descriptor.h class FileDescriptorProto; // descriptor.pb.h template class RepeatedPtrField; // repeated_field.h +} // namespace protobuf +} // namespace google + +namespace google { +namespace protobuf { namespace compiler { class CodeGenerator; // code_generator.h diff --git a/src/google/protobuf/compiler/csharp/csharp_generator.h b/src/google/protobuf/compiler/csharp/csharp_generator.h index 9b54e914..fd41d852 100644 --- a/src/google/protobuf/compiler/csharp/csharp_generator.h +++ b/src/google/protobuf/compiler/csharp/csharp_generator.h @@ -28,6 +28,8 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// Generates C# code for a given .proto file. + #ifndef GOOGLE_PROTOBUF_COMPILER_CSHARP_GENERATOR_H__ #define GOOGLE_PROTOBUF_COMPILER_CSHARP_GENERATOR_H__ @@ -40,6 +42,10 @@ namespace protobuf { namespace compiler { namespace csharp { +// CodeGenerator implementation which generates a C# source file and +// header. If you create your own protocol compiler binary and you want +// it to support C# output, you can do so by registering an instance of this +// CodeGenerator with the CommandLineInterface in your main() function. class LIBPROTOC_EXPORT Generator : public google::protobuf::compiler::CodeGenerator { virtual bool Generate( diff --git a/src/google/protobuf/compiler/js/js_generator.h b/src/google/protobuf/compiler/js/js_generator.h index 6fd7ca50..056c9897 100755 --- a/src/google/protobuf/compiler/js/js_generator.h +++ b/src/google/protobuf/compiler/js/js_generator.h @@ -28,6 +28,8 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// Generates JavaScript code for a given .proto file. + #ifndef GOOGLE_PROTOBUF_COMPILER_JS_GENERATOR_H__ #define GOOGLE_PROTOBUF_COMPILER_JS_GENERATOR_H__ @@ -90,6 +92,10 @@ struct GeneratorOptions { string* error); }; +// CodeGenerator implementation which generates a JavaScript source file and +// header. If you create your own protocol compiler binary and you want it to +// support JavaScript output, you can do so by registering an instance of this +// CodeGenerator with the CommandLineInterface in your main() function. class LIBPROTOC_EXPORT Generator : public CodeGenerator { public: Generator() {} diff --git a/src/google/protobuf/compiler/objectivec/objectivec_generator.h b/src/google/protobuf/compiler/objectivec/objectivec_generator.h index 09266b04..9ddca574 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_generator.h +++ b/src/google/protobuf/compiler/objectivec/objectivec_generator.h @@ -41,6 +41,10 @@ namespace protobuf { namespace compiler { namespace objectivec { +// CodeGenerator implementation which generates a ObjectiveC source file and +// header. If you create your own protocol compiler binary and you want it to +// support ObjectiveC output, you can do so by registering an instance of this +// CodeGenerator with the CommandLineInterface in your main() function. class LIBPROTOC_EXPORT ObjectiveCGenerator : public CodeGenerator { public: ObjectiveCGenerator(); diff --git a/src/google/protobuf/compiler/objectivec/objectivec_helpers.h b/src/google/protobuf/compiler/objectivec/objectivec_helpers.h index be20beee..7aae0fd2 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_helpers.h +++ b/src/google/protobuf/compiler/objectivec/objectivec_helpers.h @@ -28,6 +28,8 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// Helper functions for generating ObjectiveC code. + #ifndef GOOGLE_PROTOBUF_COMPILER_OBJECTIVEC_HELPERS_H__ #define GOOGLE_PROTOBUF_COMPILER_OBJECTIVEC_HELPERS_H__ diff --git a/src/google/protobuf/compiler/ruby/ruby_generator.h b/src/google/protobuf/compiler/ruby/ruby_generator.h index 75555c31..8c1dfa26 100644 --- a/src/google/protobuf/compiler/ruby/ruby_generator.h +++ b/src/google/protobuf/compiler/ruby/ruby_generator.h @@ -28,6 +28,8 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// Generates Ruby code for a given .proto file. + #ifndef GOOGLE_PROTOBUF_COMPILER_RUBY_GENERATOR_H__ #define GOOGLE_PROTOBUF_COMPILER_RUBY_GENERATOR_H__ @@ -40,6 +42,10 @@ namespace protobuf { namespace compiler { namespace ruby { +// CodeGenerator implementation for generated Ruby protocol buffer classes. +// If you create your own protocol compiler binary and you want it to support +// Ruby output, you can do so by registering an instance of this +// CodeGenerator with the CommandLineInterface in your main() function. class LIBPROTOC_EXPORT Generator : public google::protobuf::compiler::CodeGenerator { virtual bool Generate( diff --git a/src/google/protobuf/map.h b/src/google/protobuf/map.h index 1b9aa703..bfc63b0f 100644 --- a/src/google/protobuf/map.h +++ b/src/google/protobuf/map.h @@ -28,6 +28,12 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// This file defines the map container and its helpers to support protobuf maps. +// +// The Map and MapIterator types are provided by this header file. +// Please avoid using other types defined here, unless they are public +// types within Map or MapIterator, such as Map::value_type. + #ifndef GOOGLE_PROTOBUF_MAP_H__ #define GOOGLE_PROTOBUF_MAP_H__ @@ -50,9 +56,6 @@ namespace google { namespace protobuf { -// The Map and MapIterator types are provided by this header file. -// Please avoid using other types defined here, unless they are public -// types within Map or MapIterator, such as Map::value_type. template class Map; diff --git a/src/google/protobuf/util/field_comparator.h b/src/google/protobuf/util/field_comparator.h index 1b4d65b0..715560ed 100644 --- a/src/google/protobuf/util/field_comparator.h +++ b/src/google/protobuf/util/field_comparator.h @@ -28,6 +28,8 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// Defines classes for field comparison. + // Author: ksroka@google.com (Krzysztof Sroka) #ifndef GOOGLE_PROTOBUF_UTIL_FIELD_COMPARATOR_H__ diff --git a/src/google/protobuf/util/field_mask_util.h b/src/google/protobuf/util/field_mask_util.h index e79b65e9..396c9aea 100644 --- a/src/google/protobuf/util/field_mask_util.h +++ b/src/google/protobuf/util/field_mask_util.h @@ -28,6 +28,8 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// Defines utilities for the FieldMask well known type. + #ifndef GOOGLE_PROTOBUF_UTIL_FIELD_MASK_UTIL_H__ #define GOOGLE_PROTOBUF_UTIL_FIELD_MASK_UTIL_H__ diff --git a/src/google/protobuf/util/package_info.h b/src/google/protobuf/util/package_info.h new file mode 100644 index 00000000..e37e6dc0 --- /dev/null +++ b/src/google/protobuf/util/package_info.h @@ -0,0 +1,46 @@ +// Protocol Buffers - Google's data interchange format +// Copyright 2008 Google Inc. All rights reserved. +// https://developers.google.com/protocol-buffers/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +// This file exists solely to document the google::protobuf::util namespace. +// It is not compiled into anything, but it may be read by an automated +// documentation generator. + +namespace google { + +namespace protobuf { + +// Utility classes. +// +// This package contains various utilities for message comprasion, JSON +// conversion, well known types, etc. +namespace util {} + +} // namespace protobuf +} // namespace google diff --git a/src/google/protobuf/util/time_util.h b/src/google/protobuf/util/time_util.h index 1bac0897..432c9f0a 100644 --- a/src/google/protobuf/util/time_util.h +++ b/src/google/protobuf/util/time_util.h @@ -28,6 +28,8 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// Defines utilities for the Timestamp and Duration well known types. + #ifndef GOOGLE_PROTOBUF_UTIL_TIME_UTIL_H__ #define GOOGLE_PROTOBUF_UTIL_TIME_UTIL_H__ @@ -47,6 +49,7 @@ namespace google { namespace protobuf { namespace util { +// Utility functions for Timestamp and Duration. class LIBPROTOBUF_EXPORT TimeUtil { typedef google::protobuf::Timestamp Timestamp; typedef google::protobuf::Duration Duration; diff --git a/src/google/protobuf/util/type_resolver.h b/src/google/protobuf/util/type_resolver.h index 77d4416a..959f3c79 100644 --- a/src/google/protobuf/util/type_resolver.h +++ b/src/google/protobuf/util/type_resolver.h @@ -28,6 +28,8 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// Defines a TypeResolver for the Any message. + #ifndef GOOGLE_PROTOBUF_UTIL_TYPE_RESOLVER_H__ #define GOOGLE_PROTOBUF_UTIL_TYPE_RESOLVER_H__ diff --git a/src/google/protobuf/util/type_resolver_util.h b/src/google/protobuf/util/type_resolver_util.h index c0ef3c1a..c17366fc 100644 --- a/src/google/protobuf/util/type_resolver_util.h +++ b/src/google/protobuf/util/type_resolver_util.h @@ -28,6 +28,8 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// Defines utilities for the TypeResolver. + #ifndef GOOGLE_PROTOBUF_UTIL_TYPE_RESOLVER_UTIL_H__ #define GOOGLE_PROTOBUF_UTIL_TYPE_RESOLVER_UTIL_H__ -- cgit v1.2.3