ruby-protocol-buffers 1.3.0 → 1.3.1

data/.gitignore

@@ -1,13 +1,14 @@
-/*.pb.rb
+.rvmrc
+.yardoc/
 /*.d
+/*.pb.rb
 /*.proto
-.yardoc/
 Gemfile.lock
-doc/*
 coverage
-rdoc
+d/*
+doc/*
 pkg
 prof
+rdoc
 tests
-d/*
 tmp

data/.travis.yml

@@ -0,0 +1,20 @@
+language: ruby
+gemfile:
+  - Gemfile
+  # i can't find a way to use the same Gemfile and just specify --without varint
+  - Gemfile.no_varint
+rvm:
+  - "1.8.7"
+  - "1.9.3"
+  - "2.0.0"
+  - jruby-18mode # JRuby in 1.8 mode
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-18mode
+  - rbx-19mode
+matrix:
+  exclude:
+    # can't use the varint extension in jruby runs
+    - rvm: jruby-18mode
+      gemfile: Gemfile
+    - rvm: jruby-19mode
+      gemfile: Gemfile

data/Gemfile

@@ -1,4 +1,8 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in ruby-protocol-buffers.gemspec
 gemspec
+
+group :varint do
+  gem 'varint'
+end

data/Gemfile.no_varint

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in ruby-protocol-buffers.gemspec
+gemspec

data/README.md

@@ -1,5 +1,7 @@
 # Ruby Protocol Buffers
 
+[![Build Status](https://travis-ci.org/codekitchen/ruby-protocol-buffers.png?branch=master)](https://travis-ci.org/codekitchen/ruby-protocol-buffers)
+
 Protocol Buffers are a way of encoding structured data in an efficient yet
 extensible format. Google uses Protocol Buffers for almost all of its internal
 RPC protocols and file formats.
@@ -29,6 +31,11 @@ If you want to compile .proto files to ruby, you'll need `protoc` version >= 2.2
 installed in the environment where you will be compiling them.
 You do not need `protoc` installed to use the generated `.pb.rb` files.
 
+For greater performance, consider installing the varint gem as well.
+This optional gem builds a small C extension to make parsing protocol buffers
+faster. If your application uses a Gemfile, add varint to the Gemfile
+alongside ruby-protocol-buffers.
+
 ## Example
 
 Given the file test.proto:

data/Rakefile

@@ -1,20 +1,5 @@
-require 'bundler'
-Bundler::GemHelper.install_tasks
+require "bundler/gem_tasks"
 
-task :default => 'spec'
+Dir['tasks/**/*.rake'].each { |t| load t }
 
-require 'rspec/core/rake_task'
-RSpec::Core::RakeTask.new(:spec) do |t|
-  t.rspec_opts = "-c -f d"
-end
-RSpec::Core::RakeTask.new(:rcov) do |t|
-  t.rspec_opts = "-c -f d"
-  t.rcov = true
-  t.rcov_opts = ["--exclude", "spec,gems/,rubygems/"]
-end
-
-require 'yard'
-YARD::Rake::YardocTask.new(:doc) do |t|
-  version = ProtocolBuffers::VERSION
-  t.options = ["--title", "ruby protocol buffers #{version}", "--files", "LICENSE,Changelog.md"]
-end
+task :default => [:spec]

data/lib/protocol_buffers.rb

@@ -1,7 +1,6 @@
-module ProtocolBuffers
-  VERSION = File.read(File.join(File.dirname(__FILE__), "..", "VERSION")).chomp
+require 'stringio'
 
-  require 'stringio'
+module ProtocolBuffers
   # for 1.9.2 compatibility
   def self.bin_sio(*args)
     sio = StringIO.new(*args)
@@ -10,4 +9,5 @@ module ProtocolBuffers
   end
 end
 
+require 'protocol_buffers/version'
 require 'protocol_buffers/runtime/message'

data/lib/protocol_buffers/compiler.rb

@@ -52,5 +52,12 @@ module ProtocolBuffers
       (opts[:include_dirs] ||= []) << File.dirname(tempfile.path)
       compile_and_load(tempfile.path, opts)
     end
+
+    def self.available?
+      version = `protoc --version`.match(/[\d\.]+/)
+      version && version[0] >= "2.2"
+    rescue Errno::ENOENT
+      false
+    end
   end
 end

data/lib/protocol_buffers/compiler/descriptor.pb.rb

@@ -1,25 +1,26 @@
 #!/usr/bin/env ruby
 # Generated by the protocol buffer compiler. DO NOT EDIT!
 
-require 'protocol_buffers/runtime/message'
+require 'protocol_buffers'
 
 # forward declarations
-class ::FileDescriptorSet < ::ProtocolBuffers::Message; end
-class ::FileDescriptorProto < ::ProtocolBuffers::Message; end
-class ::DescriptorProto < ::ProtocolBuffers::Message; end
-class ::FieldDescriptorProto < ::ProtocolBuffers::Message; end
-class ::EnumDescriptorProto < ::ProtocolBuffers::Message; end
-class ::EnumValueDescriptorProto < ::ProtocolBuffers::Message; end
-class ::ServiceDescriptorProto < ::ProtocolBuffers::Message; end
-class ::MethodDescriptorProto < ::ProtocolBuffers::Message; end
-class ::FileOptions < ::ProtocolBuffers::Message; end
-class ::MessageOptions < ::ProtocolBuffers::Message; end
-class ::FieldOptions < ::ProtocolBuffers::Message; end
-class ::EnumOptions < ::ProtocolBuffers::Message; end
-class ::EnumValueOptions < ::ProtocolBuffers::Message; end
-class ::ServiceOptions < ::ProtocolBuffers::Message; end
-class ::MethodOptions < ::ProtocolBuffers::Message; end
-class ::UninterpretedOption < ::ProtocolBuffers::Message; end
+class FileDescriptorSet < ::ProtocolBuffers::Message; end
+class FileDescriptorProto < ::ProtocolBuffers::Message; end
+class DescriptorProto < ::ProtocolBuffers::Message; end
+class FieldDescriptorProto < ::ProtocolBuffers::Message; end
+class EnumDescriptorProto < ::ProtocolBuffers::Message; end
+class EnumValueDescriptorProto < ::ProtocolBuffers::Message; end
+class ServiceDescriptorProto < ::ProtocolBuffers::Message; end
+class MethodDescriptorProto < ::ProtocolBuffers::Message; end
+class FileOptions < ::ProtocolBuffers::Message; end
+class MessageOptions < ::ProtocolBuffers::Message; end
+class FieldOptions < ::ProtocolBuffers::Message; end
+class EnumOptions < ::ProtocolBuffers::Message; end
+class EnumValueOptions < ::ProtocolBuffers::Message; end
+class ServiceOptions < ::ProtocolBuffers::Message; end
+class MethodOptions < ::ProtocolBuffers::Message; end
+class UninterpretedOption < ::ProtocolBuffers::Message; end
+class SourceCodeInfo < ::ProtocolBuffers::Message; end
 
 class FileDescriptorSet < ::ProtocolBuffers::Message
   repeated ::FileDescriptorProto, :file, 1
@@ -29,20 +30,23 @@ end
 
 class FileDescriptorProto < ::ProtocolBuffers::Message
   optional :string, :name, 1
-  optional :string, :package_, 2
+  optional :string, :package, 2
   repeated :string, :dependency, 3
+  repeated :int32, :public_dependency, 10
+  repeated :int32, :weak_dependency, 11
   repeated ::DescriptorProto, :message_type, 4
   repeated ::EnumDescriptorProto, :enum_type, 5
-  repeated ::ServiceDescriptorProto, :service_, 6
+  repeated ::ServiceDescriptorProto, :service, 6
   repeated ::FieldDescriptorProto, :extension, 7
   optional ::FileOptions, :options, 8
+  optional ::SourceCodeInfo, :source_code_info, 9
 
   gen_methods! # new fields ignored after this point
 end
 
 class DescriptorProto < ::ProtocolBuffers::Message
   # forward declarations
-  class ::ExtensionRange < ::ProtocolBuffers::Message; end
+  class ExtensionRange < ::ProtocolBuffers::Message; end
 
   # nested messages
   class ExtensionRange < ::ProtocolBuffers::Message
@@ -65,10 +69,8 @@ end
 
 class FieldDescriptorProto < ::ProtocolBuffers::Message
   # forward declarations
-  module ::Type; end
-  module ::Label; end
 
-  # nested enums
+  # enums
   module Type
     include ::ProtocolBuffers::Enum
     TYPE_DOUBLE = 1
@@ -145,19 +147,24 @@ end
 
 class FileOptions < ::ProtocolBuffers::Message
   # forward declarations
-  module ::OptimizeMode; end
 
-  # nested enums
+  # enums
   module OptimizeMode
     include ::ProtocolBuffers::Enum
     SPEED = 1
     CODE_SIZE = 2
+    LITE_RUNTIME = 3
   end
 
   optional :string, :java_package, 1
   optional :string, :java_outer_classname, 8
   optional :bool, :java_multiple_files, 10, :default => false
-  optional ::FileOptions::OptimizeMode, :optimize_for, 9, :default => ::FileOptions::OptimizeMode::CODE_SIZE
+  optional :bool, :java_generate_equals_and_hash, 20, :default => false
+  optional ::FileOptions::OptimizeMode, :optimize_for, 9, :default => ::FileOptions::OptimizeMode::SPEED
+  optional :string, :go_package, 11
+  optional :bool, :cc_generic_services, 16, :default => false
+  optional :bool, :java_generic_services, 17, :default => false
+  optional :bool, :py_generic_services, 18, :default => false
   repeated ::UninterpretedOption, :uninterpreted_option, 999
 
   gen_methods! # new fields ignored after this point
@@ -165,6 +172,7 @@ end
 
 class MessageOptions < ::ProtocolBuffers::Message
   optional :bool, :message_set_wire_format, 1, :default => false
+  optional :bool, :no_standard_descriptor_accessor, 2, :default => false
   repeated ::UninterpretedOption, :uninterpreted_option, 999
 
   gen_methods! # new fields ignored after this point
@@ -172,23 +180,28 @@ end
 
 class FieldOptions < ::ProtocolBuffers::Message
   # forward declarations
-  module ::CType; end
 
-  # nested enums
+  # enums
   module CType
     include ::ProtocolBuffers::Enum
+    STRING = 0
     CORD = 1
     STRING_PIECE = 2
   end
 
-  optional ::FieldOptions::CType, :ctype, 1
+  optional ::FieldOptions::CType, :ctype, 1, :default => ::FieldOptions::CType::STRING
+  optional :bool, :packed, 2
+  optional :bool, :lazy, 5, :default => false
+  optional :bool, :deprecated, 3, :default => false
   optional :string, :experimental_map_key, 9
+  optional :bool, :weak, 10, :default => false
   repeated ::UninterpretedOption, :uninterpreted_option, 999
 
   gen_methods! # new fields ignored after this point
 end
 
 class EnumOptions < ::ProtocolBuffers::Message
+  optional :bool, :allow_alias, 2, :default => true
   repeated ::UninterpretedOption, :uninterpreted_option, 999
 
   gen_methods! # new fields ignored after this point
@@ -214,7 +227,7 @@ end
 
 class UninterpretedOption < ::ProtocolBuffers::Message
   # forward declarations
-  class ::NamePart < ::ProtocolBuffers::Message; end
+  class NamePart < ::ProtocolBuffers::Message; end
 
   # nested messages
   class NamePart < ::ProtocolBuffers::Message
@@ -230,6 +243,26 @@ class UninterpretedOption < ::ProtocolBuffers::Message
   optional :int64, :negative_int_value, 5
   optional :double, :double_value, 6
   optional :bytes, :string_value, 7
+  optional :string, :aggregate_value, 8
+
+  gen_methods! # new fields ignored after this point
+end
+
+class SourceCodeInfo < ::ProtocolBuffers::Message
+  # forward declarations
+  class Location < ::ProtocolBuffers::Message; end
+
+  # nested messages
+  class Location < ::ProtocolBuffers::Message
+    repeated :int32, :path, 1
+    repeated :int32, :span, 2
+    optional :string, :leading_comments, 3
+    optional :string, :trailing_comments, 4
+
+    gen_methods! # new fields ignored after this point
+  end
+
+  repeated ::SourceCodeInfo::Location, :location, 1
 
   gen_methods! # new fields ignored after this point
 end

data/lib/protocol_buffers/compiler/descriptor.proto

@@ -55,18 +55,29 @@ message FileDescriptorSet {
 // Describes a complete .proto file.
 message FileDescriptorProto {
   optional string name = 1;       // file name, relative to root of source tree
-  optional string package_ = 2;    // e.g. "foo", "foo.bar", etc.
+  optional string package = 2;    // e.g. "foo", "foo.bar", etc.
 
   // Names of files imported by this file.
   repeated string dependency = 3;
+  // Indexes of the public imported files in the dependency list above.
+  repeated int32 public_dependency = 10;
+  // Indexes of the weak imported files in the dependency list.
+  // For Google-internal migration only. Do not use.
+  repeated int32 weak_dependency = 11;
 
   // All top-level definitions in this file.
   repeated DescriptorProto message_type = 4;
   repeated EnumDescriptorProto enum_type = 5;
-  repeated ServiceDescriptorProto service_ = 6;
+  repeated ServiceDescriptorProto service = 6;
   repeated FieldDescriptorProto extension = 7;
 
   optional FileOptions options = 8;
+
+  // This field contains optional information about the original source code.
+  // You may safely remove this entire field whithout harming runtime
+  // functionality of the descriptors -- the information is needed only by
+  // development tools.
+  optional SourceCodeInfo source_code_info = 9;
 }
 
 // Describes a message type.
@@ -95,13 +106,13 @@ message FieldDescriptorProto {
     // Order is weird for historical reasons.
     TYPE_DOUBLE         = 1;
     TYPE_FLOAT          = 2;
-    TYPE_INT64          = 3;   // Not ZigZag encoded.  Negative numbers
-                               // take 10 bytes.  Use TYPE_SINT64 if negative
-                               // values are likely.
+    // Not ZigZag encoded.  Negative numbers take 10 bytes.  Use TYPE_SINT64 if
+    // negative values are likely.
+    TYPE_INT64          = 3;
     TYPE_UINT64         = 4;
-    TYPE_INT32          = 5;   // Not ZigZag encoded.  Negative numbers
-                               // take 10 bytes.  Use TYPE_SINT32 if negative
-                               // values are likely.
+    // Not ZigZag encoded.  Negative numbers take 10 bytes.  Use TYPE_SINT32 if
+    // negative values are likely.
+    TYPE_INT32          = 5;
     TYPE_FIXED64        = 6;
     TYPE_FIXED32        = 7;
     TYPE_BOOL           = 8;
@@ -117,7 +128,7 @@ message FieldDescriptorProto {
     TYPE_SFIXED64       = 16;
     TYPE_SINT32         = 17;  // Uses ZigZag encoding.
     TYPE_SINT64         = 18;  // Uses ZigZag encoding.
-  }
+  };
 
   enum Label {
     // 0 is reserved for errors
@@ -125,7 +136,7 @@ message FieldDescriptorProto {
     LABEL_REQUIRED      = 2;
     LABEL_REPEATED      = 3;
     // TODO(sanjay): Should we add LABEL_MAP?
-  }
+  };
 
   optional string name = 1;
   optional int32 number = 3;
@@ -193,6 +204,7 @@ message MethodDescriptorProto {
   optional MethodOptions options = 4;
 }
 
+
 // ===================================================================
 // Options
 
@@ -214,10 +226,15 @@ message MethodDescriptorProto {
 //   through 99999.  It is up to you to ensure that you do not use the
 //   same number for multiple options.
 // * For options which will be published and used publicly by multiple
-//   independent entities, e-mail kenton@google.com to reserve extension
-//   numbers.  Simply tell me how many you need and I'll send you back a
-//   set of numbers to use -- there's no need to explain how you intend to
-//   use them.  If this turns out to be popular, a web service will be set up
+//   independent entities, e-mail protobuf-global-extension-registry@google.com
+//   to reserve extension numbers. Simply provide your project name (e.g.
+//   Object-C plugin) and your porject website (if available) -- there's no need
+//   to explain how you intend to use them. Usually you only need one extension
+//   number. You can declare multiple options with only one extension number by
+//   putting them in a sub-message. See the Custom Options section of the docs
+//   for examples:
+//   http://code.google.com/apis/protocolbuffers/docs/proto.html#options
+//   If this turns out to be popular, a web service will be set up
 //   to automatically assign option numbers.
 
 
@@ -245,19 +262,46 @@ message FileOptions {
   // top-level extensions defined in the file.
   optional bool java_multiple_files = 10 [default=false];
 
+  // If set true, then the Java code generator will generate equals() and
+  // hashCode() methods for all messages defined in the .proto file. This is
+  // purely a speed optimization, as the AbstractMessage base class includes
+  // reflection-based implementations of these methods.
+  optional bool java_generate_equals_and_hash = 20 [default=false];
+
   // Generated classes can be optimized for speed or code size.
   enum OptimizeMode {
-    SPEED = 1;      // Generate complete code for parsing, serialization, etc.
-    CODE_SIZE = 2;  // Use ReflectionOps to implement these methods.
+    SPEED = 1;        // Generate complete code for parsing, serialization,
+                      // etc.
+    CODE_SIZE = 2;    // Use ReflectionOps to implement these methods.
+    LITE_RUNTIME = 3; // Generate code using MessageLite and the lite runtime.
   }
-  optional OptimizeMode optimize_for = 9 [default=CODE_SIZE];
+  optional OptimizeMode optimize_for = 9 [default=SPEED];
+
+  // Sets the Go package where structs generated from this .proto will be
+  // placed.  There is no default.
+  optional string go_package = 11;
 
 
+
+  // Should generic services be generated in each language?  "Generic" services
+  // are not specific to any particular RPC system.  They are generated by the
+  // main code generators in each language (without additional plugins).
+  // Generic services were the only kind of service generation supported by
+  // early versions of proto2.
+  //
+  // Generic services are now considered deprecated in favor of using plugins
+  // that generate code specific to your particular RPC system.  Therefore,
+  // these default to false.  Old code which depends on generic services should
+  // explicitly set them to true.
+  optional bool cc_generic_services = 16 [default=false];
+  optional bool java_generic_services = 17 [default=false];
+  optional bool py_generic_services = 18 [default=false];
+
   // The parser stores options it doesn't recognize here. See above.
   repeated UninterpretedOption uninterpreted_option = 999;
 
   // Clients can define custom options in extensions of this message. See above.
-  // extensions 1000 to max;
+  extensions 1000 to max;
 }
 
 message MessageOptions {
@@ -281,11 +325,16 @@ message MessageOptions {
   // the protocol compiler.
   optional bool message_set_wire_format = 1 [default=false];
 
+  // Disables the generation of the standard "descriptor()" accessor, which can
+  // conflict with a field of the same name.  This is meant to make migration
+  // from proto1 easier; new code should avoid fields named "descriptor".
+  optional bool no_standard_descriptor_accessor = 2 [default=false];
+
   // The parser stores options it doesn't recognize here. See above.
   repeated UninterpretedOption uninterpreted_option = 999;
 
   // Clients can define custom options in extensions of this message. See above.
-  // extensions 1000 to max;
+  extensions 1000 to max;
 }
 
 message FieldOptions {
@@ -293,12 +342,58 @@ message FieldOptions {
   // representation of the field than it normally would.  See the specific
   // options below.  This option is not yet implemented in the open source
   // release -- sorry, we'll try to include it in a future version!
-  optional CType ctype = 1;
+  optional CType ctype = 1 [default = STRING];
   enum CType {
+    // Default mode.
+    STRING = 0;
+
     CORD = 1;
 
     STRING_PIECE = 2;
   }
+  // The packed option can be enabled for repeated primitive fields to enable
+  // a more efficient representation on the wire. Rather than repeatedly
+  // writing the tag and type for each element, the entire array is encoded as
+  // a single length-delimited blob.
+  optional bool packed = 2;
+
+
+
+  // Should this field be parsed lazily?  Lazy applies only to message-type
+  // fields.  It means that when the outer message is initially parsed, the
+  // inner message's contents will not be parsed but instead stored in encoded
+  // form.  The inner message will actually be parsed when it is first accessed.
+  //
+  // This is only a hint.  Implementations are free to choose whether to use
+  // eager or lazy parsing regardless of the value of this option.  However,
+  // setting this option true suggests that the protocol author believes that
+  // using lazy parsing on this field is worth the additional bookkeeping
+  // overhead typically needed to implement it.
+  //
+  // This option does not affect the public interface of any generated code;
+  // all method signatures remain the same.  Furthermore, thread-safety of the
+  // interface is not affected by this option; const methods remain safe to
+  // call from multiple threads concurrently, while non-const methods continue
+  // to require exclusive access.
+  //
+  //
+  // Note that implementations may choose not to check required fields within
+  // a lazy sub-message.  That is, calling IsInitialized() on the outher message
+  // may return true even if the inner message has missing required fields.
+  // This is necessary because otherwise the inner message would have to be
+  // parsed in order to perform the check, defeating the purpose of lazy
+  // parsing.  An implementation which chooses not to check required fields
+  // must be consistent about it.  That is, for any particular sub-message, the
+  // implementation must either *always* check its required fields, or *never*
+  // check its required fields, regardless of whether or not the message has
+  // been parsed.
+  optional bool lazy = 5 [default=false];
+
+  // Is this field deprecated?
+  // Depending on the target platform, this can emit Deprecated annotations
+  // for accessors, or it will be completely ignored; in the very least, this
+  // is a formalization for deprecating fields.
+  optional bool deprecated = 3 [default=false];
 
   // EXPERIMENTAL.  DO NOT USE.
   // For "map" fields, the name of the field in the enclosed type that
@@ -314,19 +409,27 @@ message FieldOptions {
   // TODO: Fully-implement this, then remove the "experimental_" prefix.
   optional string experimental_map_key = 9;
 
+  // For Google-internal migration only. Do not use.
+  optional bool weak = 10 [default=false];
+
   // The parser stores options it doesn't recognize here. See above.
   repeated UninterpretedOption uninterpreted_option = 999;
 
   // Clients can define custom options in extensions of this message. See above.
-  // extensions 1000 to max;
+  extensions 1000 to max;
 }
 
 message EnumOptions {
+
+  // Set this option to false to disallow mapping different tag names to a same
+  // value.
+  optional bool allow_alias = 2 [default=true];
+
   // The parser stores options it doesn't recognize here. See above.
   repeated UninterpretedOption uninterpreted_option = 999;
 
   // Clients can define custom options in extensions of this message. See above.
-  // extensions 1000 to max;
+  extensions 1000 to max;
 }
 
 message EnumValueOptions {
@@ -334,7 +437,7 @@ message EnumValueOptions {
   repeated UninterpretedOption uninterpreted_option = 999;
 
   // Clients can define custom options in extensions of this message. See above.
-  // extensions 1000 to max;
+  extensions 1000 to max;
 }
 
 message ServiceOptions {
@@ -348,7 +451,7 @@ message ServiceOptions {
   repeated UninterpretedOption uninterpreted_option = 999;
 
   // Clients can define custom options in extensions of this message. See above.
-  // extensions 1000 to max;
+  extensions 1000 to max;
 }
 
 message MethodOptions {
@@ -362,9 +465,10 @@ message MethodOptions {
   repeated UninterpretedOption uninterpreted_option = 999;
 
   // Clients can define custom options in extensions of this message. See above.
-  // extensions 1000 to max;
+  extensions 1000 to max;
 }
 
+
 // A message representing a option the parser does not recognize. This only
 // appears in options protos created by the compiler::Parser class.
 // DescriptorPool resolves these when building Descriptor objects. Therefore,
@@ -390,4 +494,127 @@ message UninterpretedOption {
   optional int64 negative_int_value = 5;
   optional double double_value = 6;
   optional bytes string_value = 7;
+  optional string aggregate_value = 8;
+}
+
+// ===================================================================
+// Optional source code info
+
+// Encapsulates information about the original source file from which a
+// FileDescriptorProto was generated.
+message SourceCodeInfo {
+  // A Location identifies a piece of source code in a .proto file which
+  // corresponds to a particular definition.  This information is intended
+  // to be useful to IDEs, code indexers, documentation generators, and similar
+  // tools.
+  //
+  // For example, say we have a file like:
+  //   message Foo {
+  //     optional string foo = 1;
+  //   }
+  // Let's look at just the field definition:
+  //   optional string foo = 1;
+  //   ^       ^^     ^^  ^  ^^^
+  //   a       bc     de  f  ghi
+  // We have the following locations:
+  //   span   path               represents
+  //   [a,i)  [ 4, 0, 2, 0 ]     The whole field definition.
+  //   [a,b)  [ 4, 0, 2, 0, 4 ]  The label (optional).
+  //   [c,d)  [ 4, 0, 2, 0, 5 ]  The type (string).
+  //   [e,f)  [ 4, 0, 2, 0, 1 ]  The name (foo).
+  //   [g,h)  [ 4, 0, 2, 0, 3 ]  The number (1).
+  //
+  // Notes:
+  // - A location may refer to a repeated field itself (i.e. not to any
+  //   particular index within it).  This is used whenever a set of elements are
+  //   logically enclosed in a single code segment.  For example, an entire
+  //   extend block (possibly containing multiple extension definitions) will
+  //   have an outer location whose path refers to the "extensions" repeated
+  //   field without an index.
+  // - Multiple locations may have the same path.  This happens when a single
+  //   logical declaration is spread out across multiple places.  The most
+  //   obvious example is the "extend" block again -- there may be multiple
+  //   extend blocks in the same scope, each of which will have the same path.
+  // - A location's span is not always a subset of its parent's span.  For
+  //   example, the "extendee" of an extension declaration appears at the
+  //   beginning of the "extend" block and is shared by all extensions within
+  //   the block.
+  // - Just because a location's span is a subset of some other location's span
+  //   does not mean that it is a descendent.  For example, a "group" defines
+  //   both a type and a field in a single declaration.  Thus, the locations
+  //   corresponding to the type and field and their components will overlap.
+  // - Code which tries to interpret locations should probably be designed to
+  //   ignore those that it doesn't understand, as more types of locations could
+  //   be recorded in the future.
+  repeated Location location = 1;
+  message Location {
+    // Identifies which part of the FileDescriptorProto was defined at this
+    // location.
+    //
+    // Each element is a field number or an index.  They form a path from
+    // the root FileDescriptorProto to the place where the definition.  For
+    // example, this path:
+    //   [ 4, 3, 2, 7, 1 ]
+    // refers to:
+    //   file.message_type(3)  // 4, 3
+    //       .field(7)         // 2, 7
+    //       .name()           // 1
+    // This is because FileDescriptorProto.message_type has field number 4:
+    //   repeated DescriptorProto message_type = 4;
+    // and DescriptorProto.field has field number 2:
+    //   repeated FieldDescriptorProto field = 2;
+    // and FieldDescriptorProto.name has field number 1:
+    //   optional string name = 1;
+    //
+    // Thus, the above path gives the location of a field name.  If we removed
+    // the last element:
+    //   [ 4, 3, 2, 7 ]
+    // this path refers to the whole field declaration (from the beginning
+    // of the label to the terminating semicolon).
+    repeated int32 path = 1 [packed=true];
+
+    // Always has exactly three or four elements: start line, start column,
+    // end line (optional, otherwise assumed same as start line), end column.
+    // These are packed into a single field for efficiency.  Note that line
+    // and column numbers are zero-based -- typically you will want to add
+    // 1 to each before displaying to a user.
+    repeated int32 span = 2 [packed=true];
+
+    // If this SourceCodeInfo represents a complete declaration, these are any
+    // comments appearing before and after the declaration which appear to be
+    // attached to the declaration.
+    //
+    // A series of line comments appearing on consecutive lines, with no other
+    // tokens appearing on those lines, will be treated as a single comment.
+    //
+    // Only the comment content is provided; comment markers (e.g. //) are
+    // stripped out.  For block comments, leading whitespace and an asterisk
+    // will be stripped from the beginning of each line other than the first.
+    // Newlines are included in the output.
+    //
+    // Examples:
+    //
+    //   optional int32 foo = 1;  // Comment attached to foo.
+    //   // Comment attached to bar.
+    //   optional int32 bar = 2;
+    //
+    //   optional string baz = 3;
+    //   // Comment attached to baz.
+    //   // Another line attached to baz.
+    //
+    //   // Comment attached to qux.
+    //   //
+    //   // Another line attached to qux.
+    //   optional double qux = 4;
+    //
+    //   optional string corge = 5;
+    //   /* Block comment attached
+    //    * to corge.  Leading asterisks
+    //    * will be removed. */
+    //   /* Block comment attached to
+    //    * grault. */
+    //   optional int32 grault = 6;
+    optional string leading_comments = 3;
+    optional string trailing_comments = 4;
+  }
 }