Merge branch 'main' into patch-1

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/overview.md

@@ -245,12 +245,12 @@ When defining `.proto` files, you can specify that a field is either `optional`
 or `repeated` (proto2 and proto3) or `singular` (proto3). (The option to set a
 field to `required` is absent in proto3 and strongly discouraged in proto2. For
 more on this, see "Required is Forever" in
-[Specifying Field Rules](/programming-guides/proto3#specifying-field-rules).)
+[Specifying Field Rules](/programming-guides/proto3/#specifying-field-rules).)
 
 After setting the optionality/repeatability of a field, you specify the data
 type. Protocol buffers support the usual primitive data types, such as integers,
 booleans, and floats. For the full list, see
-[Scalar Value Types](/programming-guides/proto3#scalar).
+[Scalar Value Types](/programming-guides/proto3/#scalar).
 
 A field can also be of:
 

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
@@ -296,7 +296,7 @@ Missing `optional` fields are easy to encode: we just leave out the record if
 it's not present. This means that "huge" protos with only a few fields set are
 quite sparse.
 
-`repeated` fields are a bit more compicated. Ordinary (not [packed](#packed))
+`repeated` fields are a bit more complicated. Ordinary (not [packed](#packed))
 repeated fields emit one record for every element of the field. Thus, if we have
 
 ```proto

content/programming-guides/proto.md content/programming-guides/proto2.mdcontent/programming-guides/proto.md renamed to content/programming-guides/proto2.md

@@ -6,6 +6,8 @@ linkTitle: "Language Guide (proto 2)"
 no_list: "true"
 type: docs
 description: "This topic covers how to use the version 2 of Protocol Buffers in your project. It contains language-agnostic content. For information specific to the language you're using, see the corresponding documentation for your language."
+aliases: 
+  - /programming-guides/proto/
 ---
 
 This guide describes how to use the protocol buffer language to structure your

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}
 
@@ -267,17 +267,19 @@ The compiler will generate the following accessor methods:
     whatever value is written into the given string.
 -   `void clear_foo()`: Clears the value of the field. After calling this,
     `has_foo()` will return `false` and `foo()` will return the default value.
--   `void set_allocated_foo(string* value)`: Sets the `string` object to the
-    field and frees the previous field value if it exists. If the `string`
-    pointer is not `NULL`, the message takes ownership of the allocated `string`
-    object and `has_foo()` will return `true`. The message is free to delete the
-    allocated `string` object at any time, so references to the object may be
-    invalidated. Otherwise, if the `value` is `NULL`, the behavior is the same
-    as calling `clear_foo()`.
--   `string* release_foo()`: Releases the ownership of the field and returns the
-    pointer of the `string` object. After calling this, caller takes the
-    ownership of the allocated `string` object, `has_foo()` will return `false`,
-    and `foo()` will return the default value.
+-   `void set_allocated_foo(string* value)`:
+    Sets the `string`
+    object to the field and frees the previous field value if it exists. If the
+    `string` pointer is not `NULL`, the message takes ownership of the allocated
+    `string` object and `has_foo()` will return `true`. The message is free to
+    delete the allocated `string` object at any time, so references to the
+    object may be invalidated. Otherwise, if the `value` is `NULL`, the behavior
+    is the same as calling `clear_foo()`.
+-   `string* release_foo()`:
+    Releases the
+    ownership of the field and returns the pointer of the `string` object. After
+    calling this, caller takes the ownership of the allocated `string` object,
+    `has_foo()` will return `false`, and `foo()` will return the default value.
 
 ### Singular String Fields (proto3) {#proto3_string}
 
@@ -309,16 +311,18 @@ The compiler will generate the following accessor methods:
     return whatever value is written into the given string.
 -   `void clear_foo()`: Clears the value of the field. After calling this,
     `foo()` will return the empty string/empty bytes.
--   `void set_allocated_foo(string* value)`: Sets the `string` object to the
-    field and frees the previous field value if it exists. If the `string`
-    pointer is not `NULL`, the message takes ownership of the allocated `string`
-    object. The message is free to delete the allocated `string` object at any
-    time, so references to the object may be invalidated. Otherwise, if the
-    `value` is `NULL`, the behavior is the same as calling `clear_foo()`.
--   `string* release_foo()`: Releases the ownership of the field and returns the
-    pointer of the `string` object. After calling this, caller takes the
-    ownership of the allocated `string` object and `foo()` will return the empty
-    string/empty bytes.
+-   `void set_allocated_foo(string* value)`:
+    Sets the `string`
+    object to the field and frees the previous field value if it exists. If the
+    `string` pointer is not `NULL`, the message takes ownership of the allocated
+    `string` object. The message is free to delete the allocated `string` object
+    at any time, so references to the object may be invalidated. Otherwise, if
+    the `value` is `NULL`, the behavior is the same as calling `clear_foo()`.
+-   `string* release_foo()`:
+    Releases the
+    ownership of the field and returns the pointer of the `string` object. After
+    calling this, caller takes the ownership of the allocated `string` object
+    and `foo()` will return the empty string/empty bytes.
 
 ### Singular Enum Fields (proto2) {#enum_field}
 
@@ -465,8 +469,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 +889,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 {