Merge pull request protocolbuffers#255 from Logofile/sync

Documentation change

Author: Logofile

content/programming-guides/field_presence.md

@@ -6,7 +6,7 @@ description = "Explains the various presence-tracking disciplines for protobuf f
 type = "docs"
 +++
 
-## Background
+## Background {#background}
 
 *Field presence* is the notion of whether a protobuf field has a value. There
 are two different manifestations of presence for protobufs: *implicit presence*,
@@ -18,15 +18,15 @@ recommend always adding the `optional` label for proto3 basic types. This
 provides a smoother path to editions, which uses explicit presence by
 default.{{% /alert %}}
 
-### Presence Disciplines
+### Presence Disciplines {#disciplines}
 
 *Presence disciplines* define the semantics for translating between the *API
 representation* and the *serialized representation*. The *implicit presence*
 discipline relies upon the field value itself to make decisions at
 (de)serialization time, while the *explicit presence* discipline relies upon the
 explicit tracking state instead.
 
-### Presence in *Tag-value stream* (Wire Format) Serialization
+### Presence in *Tag-value stream* (Wire Format) Serialization {#presence-tag-value}
 
 The wire format is a stream of tagged, *self-delimiting* values. By definition,
 the wire format represents a sequence of *present* values. In other words, every
@@ -66,7 +66,7 @@ deserializing wire-formatted messages:
     APIs. However, out-of-range values may be stored as *unknown fields* in the
     API, even though the wire-format tag was recognized.
 
-### Presence in *Named-field Mapping* Formats
+### Presence in *Named-field Mapping* Formats {#presence-named-field}
 
 Protobufs can be represented in human-readable, textual forms. Two notable
 formats are TextFormat (the output format produced by generated message
@@ -104,7 +104,7 @@ practice, however, presence correctness can vary depending upon implementation
 choices, especially if JSON was chosen as a means to interoperate with clients
 not using protobufs.
 
-### Presence in Proto2 APIs
+### Presence in Proto2 APIs {#presence-proto2}
 
 This table outlines whether presence is tracked for fields in proto2 APIs (both
 for generated APIs and using dynamic reflection):
@@ -147,7 +147,7 @@ several methods:
 Repeated fields and maps do not track presence: there is no distinction between
 an *empty* and a *not-present* repeated field.
 
-### Presence in Proto3 APIs
+### Presence in Proto3 APIs {#presence-proto3}
 
 This table outlines whether presence is tracked for fields in proto3 APIs (both
 for generated APIs and using dynamic reflection):
@@ -187,7 +187,7 @@ required to have an enumerator value which maps to 0. By convention, this is an
 the domain of valid values for the application, this behavior can be thought of
 as tantamount to *explicit presence*.
 
-### Presence in Editions APIs
+### Presence in Editions APIs {#presence-editions}
 
 This table outlines whether presence is tracked for fields in editions APIs
 (both for generated APIs and using dynamic reflection):
@@ -239,7 +239,7 @@ For a singular field with numeric, enum, or string type:
 exception to this behavior is Dart, which generates `has_` methods with proto3
 proto schema files.{{% /alert %}}
 
-### Considerations for Merging
+### Considerations for Merging {#merging}
 
 Under the *implicit presence* rules, it is effectively impossible for a target
 field to merge-from its default value (using the protobuf's API merging
@@ -256,7 +256,7 @@ Updating to set a default value in this case requires some external mechanism,
 such as `FieldMask`. However, if presence *is* tracked, then all explicitly-set
 values -- even default values -- will be merged into the target.
 
-### Considerations for change-compatibility
+### Considerations for change-compatibility {#change-compatibility}
 
 Changing a field between *explicit presence* and *implicit presence* is a
 binary-compatible change for serialized values in wire format. However, the
@@ -334,7 +334,7 @@ this is not a safe change: client A requires (by `assert`) that the field is
 present; even without any modifications through the API, that requirement fails
 in a value- and peer-dependent case.
 
-## How to Enable *Explicit Presence* in Proto3
+## How to Enable *Explicit Presence* in Proto3 {#enable-explicit-proto3}
 
 These are the general steps to use field tracking support for proto3:
 
@@ -344,7 +344,7 @@ These are the general steps to use field tracking support for proto3:
 1.  Use the generated "hazzer" methods and "clear" methods in application code,
     instead of comparing or setting default values.
 
-### `.proto` File Changes
+### `.proto` File Changes {#proto-file-changes}
 
 This is an example of a proto3 message with fields which follow both *no
 presence* and *explicit presence* semantics:
@@ -362,7 +362,7 @@ message MyMessage {
 }
 ```
 
-### `protoc` Invocation
+### `protoc` Invocation {#protoc-invocation}
 
 Presence tracking for proto3 messages is enabled by default
 [since v3.15.0](https://github.com/protocolbuffers/protobuf/releases/tag/v3.15.0)
@@ -399,7 +399,7 @@ message Msg {
 In the examples, a function `GetProto` constructs and returns a message of type
 `Msg` with unspecified contents.
 
-#### C++ Example
+#### C++ Example {#cpp-example}
 
 Implicit presence:
 
@@ -427,7 +427,7 @@ if (m.has_foo()) {
 }
 ```
 
-#### C# Example
+#### C# Example {#csharp-example}
 
 Implicit presence:
 
@@ -455,7 +455,7 @@ if (m.HasFoo) {
 }
 ```
 
-#### Go Example
+#### Go Example {#go-example}
 
 Implicit presence:
 
@@ -483,7 +483,7 @@ if m.Foo != nil {
 }
 ```
 
-#### Java Example
+#### Java Example {#java-example}
 
 These examples use a `Builder` to demonstrate clearing. Simply checking presence
 and getting values from a `Builder` follows the same API as the message type.
@@ -514,7 +514,7 @@ if (m.hasFoo()) {
 }
 ```
 
-#### Python Example
+#### Python Example {#python-example}
 
 Implicit presence:
 
@@ -540,7 +540,7 @@ else:
   m.foo = 1
 ```
 
-#### Ruby Example
+#### Ruby Example {#ruby-example}
 
 Implicit presence:
 
@@ -568,7 +568,7 @@ else
 end
 ```
 
-#### Javascript Example
+#### Javascript Example {#js-example}
 
 Implicit presence:
 
@@ -596,7 +596,7 @@ if (m.hasFoo()) {
 }
 ```
 
-#### Objective-C Example
+#### Objective-C Example {#objc-example}
 
 Implicit presence:
 

content/programming-guides/json.md

@@ -21,11 +21,11 @@ topic.
 
 When parsing JSON-encoded data into a protocol buffer, if a value is missing or
 if its value is `null`, it will be interpreted as the corresponding
-[default value](/programming-guides/editions#default).
-Multiple values for singular fields (using duplicate or equivalent JSON keys)
-are accepted and the last value is retained, as with binary format parsing. Note
-that not all protobuf JSON parser implementations are conformant, and some
-nonconformant implementations may reject duplicate keys instead.
+[default value](/programming-guides/editions#default). Multiple values for
+singular fields (using duplicate or equivalent JSON keys) are accepted and the
+last value is retained, as with binary format parsing. Note that not all
+protobuf JSON parser implementations are conformant, and some nonconformant
+implementations may reject duplicate keys instead.
 
 When generating JSON-encoded output from a protocol buffer, if a protobuf field
 has the default value and if the field doesn't support field presence, it will

content/reference/cpp/arenas.md

@@ -11,7 +11,7 @@ buffer compiler generates in addition to the code described in the
 [C++ Generated Code Guide](/reference/cpp/cpp-generated)
 when arena allocation is enabled. It assumes that you are familiar with the
 material in the
-[language guide](/programming-guides/proto2) and the
+[language guide](/programming-guides/editions) and the
 [C++ Generated Code Guide](/reference/cpp/cpp-generated).
 
 ## Why Use Arena Allocation? {#why}
@@ -81,7 +81,7 @@ can see a more extensive [example](#example) at the end of the document.
 ## Arena Class API {#arenaclass}
 
 You create message objects on the arena using the
-[`google::protobuf::Arena`](/reference/cpp/api-docs/google.protobuf.arena.md)
+[`google::protobuf::Arena`](/reference/cpp/api-docs/google.protobuf.arena)
 class. This class implements the following public methods.
 
 ### Constructors {#constructors}
@@ -253,11 +253,10 @@ message objects are allocated depends on where they are defined:
     arena. This means that when the arena is destroyed, the object will be freed
     along with the objects on the arena itself.
 
-For either of these field definitions:
+For the field definition:
 
 ```proto
-optional Bar foo = 1;
-required Bar foo = 1;
+Bar foo = 1;
 ```
 
 The following methods are added or have some special behavior when arena
@@ -538,30 +537,29 @@ allocation API.
 
 ```proto
 // my_feature.proto
+edition = "2023";
 
-syntax = "proto2";
 import "nested_message.proto";
 
 package feature_package;
 
 // NEXT Tag to use: 4
 message MyFeatureMessage {
-  optional string feature_name = 1;
+  string feature_name = 1;
   repeated int32 feature_data = 2;
-  optional NestedMessage nested_message = 3;
+  NestedMessage nested_message = 3;
 };
 ```
 
 ```proto
 // nested_message.proto
-
-syntax = "proto2";
+edition = "2023";
 
 package feature_package;
 
 // NEXT Tag to use: 2
 message NestedMessage {
-  optional int32 feature_id = 1;
+  int32 feature_id = 1;
 };
 ```
 
@@ -575,7 +573,7 @@ Arena arena;
 MyFeatureMessage* arena_message =
    google::protobuf::Arena::Create<MyFeatureMessage>(&arena);
 
-arena_message->set_feature_name("Proto2 Arena");
+arena_message->set_feature_name("Editions Arena");
 arena_message->mutable_feature_data()->Add(2);
 arena_message->mutable_feature_data()->Add(4);
 arena_message->mutable_nested_message()->set_feature_id(247);

content/reference/csharp/csharp-generated.md

@@ -6,21 +6,12 @@ description = "Describes exactly what C# code the protocol buffer compiler gener
 type = "docs"
 +++
 
-You should
-read the
-[proto3 language guide](/programming-guides/proto3)
+You should read the
+[proto2 language guide](/programming-guides/proto2),
+[proto3 language guide](/programming-guides/proto3), or
+[editions language guide](/programming-guides/editions)
 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/proto2) 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 %}}
-
 ## Compiler Invocation {#invocation}
 
 The protocol buffer compiler produces C\# output when invoked with the
@@ -31,13 +22,6 @@ subdirectories of the specified directory. The compiler creates a single source
 file for each `.proto` file input, defaulting to an extension of `.cs` but
 configurable via compiler options.
 
-Only `proto3` messages are supported by the C\# code generator. Ensure that each
-`.proto` file begins with a declaration of:
-
-```proto
-syntax = "proto3";
-```
-
 ### C\#-specific Options {#compiler_options}
 
 You can provide further C\# options to the protocol buffer compiler using the
@@ -123,7 +107,8 @@ is provided as part of Protocol Buffers. A cut down version of `timestamp.proto`
 looks like this:
 
 ```proto
-syntax = "proto3";
+edition = "2023";
+
 package google.protobuf;
 option csharp_namespace = "Google.Protobuf.WellKnownTypes";
 
@@ -331,14 +316,14 @@ method.
 
 ### Wrapper Type Fields {#wrapper_types}
 
-Most of the well-known types in proto3 do not affect code generation, but the
-wrapper types (`StringWrapper`, `Int32Wrapper` etc) change the type and
-behaviour of the properties.
+Most of the well-known types do not affect code generation, but the wrapper
+types (such as `StringWrapper` and `Int32Wrapper`) change the type and behavior
+of the properties.
 
-All of the wrapper types that correspond to C\# value types (`Int32Wrapper`,
-`DoubleWrapper`, `BoolWrapper` etc) are mapped to `Nullable<T>` where `T` is the
-corresponding non-nullable type. For example, a field of type `DoubleValue`
-results in a C\# property of type `Nullable<double>`.
+All of the wrapper types that correspond to C\# value types (such as
+`Int32Wrapper`, `DoubleWrapper`, and `BoolWrapper`) are mapped to `Nullable<T>`
+where `T` is the corresponding non-nullable type. For example, a field of type
+`DoubleValue` results in a C\# property of type `Nullable<double>`.
 
 Fields of type `StringWrapper` or `BytesWrapper` result in C\# properties of
 type `string` and `ByteString` being generated, but with a default value of

content/reference/rust/rust-generated.md

@@ -12,9 +12,9 @@ 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/proto2.md)
+[proto2 language guide](/programming-guides/proto2)
 and/or
-[proto3 language guide](/programming-guides/proto3.md)
+[proto3 language guide](/programming-guides/proto3)
 before reading this document.
 
 ## Protobuf Rust {#rust}
@@ -26,7 +26,7 @@ sit on top of other existing protocol buffer implementations that we refer to as
 The decision to support multiple non-Rust kernels has significantly influenced
 our public API, including the choice to use custom types like `ProtoStr` over
 Rust std types like `str`. See
-[Rust Proto Design Decisions](/reference/rust/rust-design-decisions.md)
+[Rust Proto Design Decisions](/reference/rust/rust-design-decisions)
 for more on this topic.
 
 ## Generated Filenames {#filenames}