Merge pull request #38 from Logofile/sync

Project import generated by Copybara.

Author: Logofile

content/_index.md

@@ -36,7 +36,8 @@ message Person {
 </div>
 <div class="col-md">
 
-```proto
+```java
+// Java code
 Person john = Person.newBuilder()
     .setId(1234)
     .setName("John Doe")
@@ -51,7 +52,8 @@ john.writeTo(output);
 </div>
 <div class="col-md">
 
-```proto
+```cpp
+// C++ code
 Person john;
 fstream input(argv[1],
     ios::in | ios::binary);

content/includes/version-tables.css

@@ -1,5 +1,5 @@
 table tbody, th, td {
-  border: 1px solid #818589;
+  border: 1px solid #818589 !important;
   padding-top: 2px;
   padding-bottom: 2px;
   padding-left: 5px;

content/programming-guides/api.md

@@ -668,6 +668,10 @@ system."
 If the enhancement field in `PhotoEnhancementReply` were a scalar or enum, this
 would be much harder to support.
 
+This applies equally to maps. It is much easier to add additional fields to a
+map value if it's already a message rather than having to migrate from
+`map<string, string>` to `map<string, MyProto>`.
+
 One exception:
 
 Latency-critical applications will find parallel arrays of primitive types are

content/programming-guides/encoding.md

@@ -204,7 +204,7 @@ Signed Original | Encoded As
 Using some bit tricks, it's cheap to convert `n` into its ZigZag representation:
 
 ```
-n + n + (n < 0)
+(n + n) ^ -(n < 0) - (n < 0)
 ```
 
 Here, we assume that the boolean `n < 0` is converted into an integer 1 if true

content/reference/cpp/api-docs/google.protobuf.map.md

@@ -15,8 +15,8 @@ generated code are highlighted - note that these differences are in the
 generated code as described in this document, not the base message
 classes/interfaces, which are the same in both versions. You should read the
 [proto2 language guide](/programming-guides/proto) and/or
-[proto3 language guide](/programming-guides/proto3) before reading this
-document.
+[proto3 language guide](/programming-guides/proto3)
+before reading this document.
 
 ## Compiler Invocation {#invocation}
 
@@ -465,8 +465,8 @@ The compiler will generate the following accessor methods:
 -   `int foo_size() const`: Returns the number of elements currently in the
     field.
 -   `const string& foo(int index) const`: Returns the element at the given
-    zero-based index. Calling this method with index outside of [0, foo_size()-1]
-    yields undefined behavior.
+    zero-based index. Calling this method with index outside of [0,
+    foo_size()-1] yields undefined behavior.
 -   `void set_foo(int index, const string& value)`: Sets the value of the
     element at the given zero-based index.
 -   `void set_foo(int index, const char* value)`: Sets the value of the element
@@ -885,7 +885,8 @@ it is put into a map field as if it is a known enum value.
 
 ## Any
 
-Given an [`Any`](/programming-guides/proto3#any) field like this:
+Given an [`Any`](/programming-guides/proto3#any) field
+like this:
 
 ```proto
 import "google/protobuf/any.proto";

content/reference/cpp/cpp-generated.md

@@ -11,14 +11,15 @@ description: "This topic describes exactly what C# code the protocol buffer comp
 
 This page describes exactly what C\# code the protocol buffer compiler generates
 for protocol definitions using `proto3` syntax. You should read the
-[proto3 language guide](/programming-guides/proto3) before reading this
-document.
+[proto3 language guide](/programming-guides/proto3)
+before reading this document.
 
 {{% alert title="Note" color="note" %}}
-The protobuf compiler can generate C\# interfaces for definitions
-using `proto2` syntax starting from release 3.10. Refer to the
-[proto2 language guide](/programming-guides/proto) for details of the
-semantics of `proto2` definitions, and see `docs/csharp/proto2.md`
+The protobuf compiler can generate C\# interfaces for definitions using `proto2`
+syntax starting from release 3.10. Refer to the
+[proto2 language guide](/programming-guides/proto) for
+details of the semantics of `proto2` definitions, and see
+`docs/csharp/proto2.md`
 ([view on GitHub](https://github.com/protocolbuffers/protobuf/blob/master/docs/csharp/proto2.md))
 for details on the generated C\# code for proto2.
 {{% /alert %}}
@@ -109,7 +110,8 @@ The `namespace` is inferred from the proto's `package`, using the same
 conversion rules as the file name. For example, a proto package of
 `example.high_score` would result in a namespace of `Example.HighScore`. You can
 override the default generated namespace for a particular .proto using the
-`csharp_namespace` [file option](/programming-guides/proto3#options).
+`csharp_namespace`
+[file option](/programming-guides/proto3#options).
 
 Each top-level enum and message results in an enum or class being declared as
 members of the namespace. Additionally, a single static partial class is always

content/reference/csharp/csharp-generated.md

@@ -14,9 +14,9 @@ any given protocol definition. Any differences between proto2 and proto3
 generated code are highlighted - note that these differences are in the
 generated code as described in this document, not the base API, which are the
 same in both versions. You should read the
-[proto2 language guide](/programming-guides/proto) and/or the
-[proto3 language guide](/programming-guides/proto3) before reading this
-document.
+[proto2 language guide](/programming-guides/proto) and/or
+the [proto3 language guide](/programming-guides/proto3)
+before reading this document.
 
 ## Compiler Invocation {#invocation}
 
@@ -101,8 +101,8 @@ message in the `.proto` file.
 
 Note that the generated names always use camel-case naming, even if the field
 name in the `.proto` file uses lower-case with underscores
-([as it should](/programming-guides/style)). The case-conversion works
-as follows:
+([as it should](/programming-guides/style)). The
+case-conversion works as follows:
 
 1.  For each underscore in the name, the underscore is removed, and the
     following letter is capitalized.
@@ -132,7 +132,8 @@ The compiler will generate the following accessor methods in the message class:
     `hasFoo()` will return `false` and `get foo` will return the default value.
 
 For other simple field types, the corresponding Dart type is chosen according to
-the [scalar value types table](/programming-guides/proto#scalar).
+the
+[scalar value types table](/programming-guides/proto#scalar).
 For message and enum types, the value type is replaced with the message or enum
 class.
 
@@ -228,7 +229,8 @@ import 'package:fixnum/fixnum.dart';
 
 ### Map Fields
 
-Given a [`map`](/programming-guides/proto3#maps) field definition like this:
+Given a [`map`](/programming-guides/proto3#maps) field
+definition like this:
 
 ```proto
 map<int32, int32> map_field = 1;
@@ -242,7 +244,8 @@ The compiler will generate the following getter:
 
 ## Any
 
-Given an [`Any`](/programming-guides/proto3#any) field like this:
+Given an [`Any`](/programming-guides/proto3#any) field
+like this:
 
 ```proto
 import "google/protobuf/any.proto";
@@ -285,7 +288,8 @@ and unpack the `Any`'s values:
 
 ## Oneof
 
-Given a [`oneof`](/programming-guides/proto3#oneof) definition like this:
+Given a [`oneof`](/programming-guides/proto3#oneof)
+definition like this:
 
 ```proto
 message Foo {
@@ -383,8 +387,8 @@ The protocol buffer compiler will generate a class called `Bar`, which extends
 ## Extensions (proto2 only) {#extension}
 
 Given a file `foo_test.proto` including a message with an
-[extension range](/programming-guides/proto#extensions) and a top-level
-extension definition:
+[extension range](/programming-guides/proto#extensions)
+and a top-level extension definition:
 
 ```proto
 message Foo {

content/reference/dart/dart-generated.md

@@ -11,13 +11,14 @@ description: "This topic describes exactly what Kotlin code the protocol buffer
 
 This page describes exactly what Kotlin code the protocol buffer compiler
 generates for any given protocol definition, in addition to the code generated
-for [Java](/reference/java/java-generated). Any differences
-between proto2 and proto3 generated code are highlighted—note that these
-differences are in the generated code as described in this document, not the
-base message classes/interfaces, which are the same in both versions. You should
-read the [proto2 language guide](/programming-guides/proto) and/or
-[proto3 language guide](/programming-guides/proto3) before reading this
-document.
+for [Java](/reference/java/java-generated). Any
+differences between proto2 and proto3 generated code are highlighted—note
+that these differences are in the generated code as described in this document,
+not the base message classes/interfaces, which are the same in both versions.
+You should read the
+[proto2 language guide](/programming-guides/proto) and/or
+[proto3 language guide](/programming-guides/proto3)
+before reading this document.
 
 ## Compiler Invocation {#invocation}
 
@@ -117,8 +118,8 @@ properties on the message object from the getters generated by Java.)
 
 Note that properties always use camel-case naming, even if the field name in the
 `.proto` file uses lower-case with underscores
-([as it should](/programming-guides/style)). The case-conversion works
-as follows:
+([as it should](/programming-guides/style)). The
+case-conversion works as follows:
 
 1.  For each underscore in the name, the underscore is removed, and the
     following letter is capitalized.
@@ -149,7 +150,8 @@ The compiler will generate the following accessors in the DSL:
     `hasFoo()` will return `false` and `getFoo()` will return the default value.
 
 For other simple field types, the corresponding Java type is chosen according to
-the [scalar value types table](/programming-guides/proto#scalar).
+the
+[scalar value types table](/programming-guides/proto#scalar).
 For message and enum types, the value type is replaced with the message or enum
 class. As the message type is still defined in Java, unsigned types in the
 message are represented using the standard corresponding signed types in the
@@ -192,7 +194,8 @@ The compiler will generate the following property in the DSL:
     `getFoo()` will return the default value for the field's type.
 
 For other simple field types, the corresponding Java type is chosen according to
-the [scalar value types table](/programming-guides/proto#scalar).
+the
+[scalar value types table](/programming-guides/proto#scalar).
 For message and enum types, the value type is replaced with the message or enum
 class. As the message type is still defined in Java, unsigned types in the
 message are represented using the standard corresponding signed types in the
@@ -257,7 +260,8 @@ underlying builder, while preventing mutability from \"escaping\" the DSL, which
 could cause confusing side effects.
 
 For other simple field types, the corresponding Java type is chosen according to
-the [scalar value types table](/programming-guides/proto#scalar).
+the
+[scalar value types table](/programming-guides/proto#scalar).
 For message and enum types, the type is the message or enum class.
 
 ### Oneof Fields
@@ -283,7 +287,8 @@ The compiler will generate the following accessor methods in the DSL:
     is `FOO`. Otherwise, returns the default value of this field.
 
 For other simple field types, the corresponding Java type is chosen according to
-the [scalar value types table](/programming-guides/proto#scalar).
+the
+[scalar value types table](/programming-guides/proto#scalar).
 For message and enum types, the value type is replaced with the message or enum
 class.
 

content/reference/kotlin/kotlin-generated.md

@@ -13,8 +13,8 @@ This page describes exactly what Objective-C code the protocol buffer compiler
 generates for any given protocol definition. Any differences between proto2 and
 proto3 generated code are highlighted. You should read the
 [proto2 language guide](/programming-guides/proto) and/or
-[proto3 language guide](/programming-guides/proto3) before reading this
-document.
+[proto3 language guide](/programming-guides/proto3)
+before reading this document.
 
 ## Compiler invocation {#invocation}
 
@@ -171,11 +171,11 @@ The behaviors for this interface are as follows:
 ### Unknown fields (proto2 only)
 
 If a message created with an
-[older version](/programming-guides/proto#updating) of your .proto
-definition is parsed with code generated from a newer version (or vice versa),
-the message may contain optional or repeated fields that the \"new\" code does
-not recognize. In proto2 generated code, these fields are not discarded and are
-stored in the message's `unknownFields` property.
+[older version](/programming-guides/proto#updating) of
+your .proto definition is parsed with code generated from a newer version (or
+vice versa), the message may contain optional or repeated fields that the
+\"new\" code does not recognize. In proto2 generated code, these fields are not
+discarded and are stored in the message's `unknownFields` property.
 
 ```objc
 @property(nonatomic, copy, nullable) GPBUnknownFieldSet *unknownFields;
@@ -289,8 +289,8 @@ typedef GPB_ENUM(Foo_FieldNumber) {
 
 #### Default values {#default}
 
-The [default value](/programming-guides/proto3#default) for
-numeric types is `0`.
+The [default value](/programming-guides/proto3#default)
+for numeric types is `0`.
 
 The default value for strings is `@""`, and the default value for bytes is
 `[NSData data]`.
@@ -443,8 +443,8 @@ typedef GPB_ENUM(Foo_FieldNumber) {
 
 #### Default values (optional fields only) {#default}
 
-The [default value](/programming-guides/proto#optional) for
-numeric types, if no explicit default was specified by the user, is `0`.
+The [default value](/programming-guides/proto#optional)
+for numeric types, if no explicit default was specified by the user, is `0`.
 
 The default value for strings is `@""`, and the default value for bytes is
 `[NSData data]`.
@@ -542,10 +542,10 @@ For string, bytes and message fields, elements of the array are `NSString*`,
 
 #### Default values {#repeateddefault}
 
-The [default value](/programming-guides/proto3#default) for a
-repeated field is to be empty. In Objective-C generated code, this is an empty
-`GPB<VALUE>Array`. If you access an empty repeated field, you'll get back an
-empty array that you can update like any other repeated field array.
+The [default value](/programming-guides/proto3#default)
+for a repeated field is to be empty. In Objective-C generated code, this is an
+empty `GPB<VALUE>Array`. If you access an empty repeated field, you'll get back
+an empty array that you can update like any other repeated field array.
 
 ```objc
 Foo *myFoo = [[Foo alloc] init];
@@ -677,8 +677,9 @@ function and to access raw values.
 
 ### Oneof fields {#oneof}
 
-Given a message with [oneof](/programming-guides/proto3#oneof)
-field definitions:
+Given a message with
+[oneof](/programming-guides/proto3#oneof) field
+definitions:
 
 ```proto
 message Order {
@@ -769,8 +770,8 @@ where:
 
 #### Default values {#repeateddefault}
 
-The [default value](/programming-guides/proto3#default) for a map
-field is empty. In Objective-C generated code, this is an empty
+The [default value](/programming-guides/proto3#default)
+for a map field is empty. In Objective-C generated code, this is an empty
 `GBP<KEY><VALUE>Dictionary`. If you access an empty map field, you'll get back
 an empty dictionary that you can update like any other map field.
 
@@ -1100,9 +1101,9 @@ If you use any of the message types provided with proto3, they will in general
 just use their proto definitions in generated Objective-C code, though we supply
 some basic conversion methods in categories to make using them simpler. Note
 that we do not have special APIs for all well-known types yet, including
-[`Any`](/programming-guides/proto3#any) (there is currently no
-helper method to convert an `Any`'s message value into a message of the
-appropriate type).
+[`Any`](/programming-guides/proto3#any) (there is
+currently no helper method to convert an `Any`'s message value into a message of
+the appropriate type).
 
 ### Time Stamps