Merge pull request #105 from Logofile/sync

Periodic documentation update

Author: Logofile

content/editions/features.md

@@ -49,7 +49,7 @@ and after of a proto3 file.
 The following code sample shows a proto2 file:
 
 ```proto
-syntax = "proto2"
+syntax = "proto2";
 
 enum Foo {
   A = 2;
@@ -62,7 +62,7 @@ After running [Prototiller](#prototiller), the equivalent code might look like
 this:
 
 ```proto
-edition = "2023"
+edition = "2023";
 
 enum Foo {
   option features.enum_type = CLOSED;
@@ -104,7 +104,7 @@ for more information.
 The following code sample shows a proto2 file:
 
 ```proto
-syntax = "proto2"
+syntax = "proto2";
 
 message Foo {
   required int32 x = 1;
@@ -116,7 +116,7 @@ message Foo {
 After running Prototiller, the equivalent code might look like this:
 
 ```proto
-edition = "2023"
+edition = "2023";
 
 message Foo {
   int32 x = 1 [features.field_presence = LEGACY_REQUIRED];
@@ -140,7 +140,7 @@ message Bar {
 After running Prototiller, the equivalent code might look like this:
 
 ```proto
-edition = "2023"
+edition = "2023";
 option features.field_presence = IMPLICIT;
 
 message Bar {
@@ -227,7 +227,7 @@ and after of a proto3 file.
 The following code sample shows a proto2 file:
 
 ```proto
-syntax = "proto2"
+syntax = "proto2";
 
 message Foo {
   group Bar = 1 {
@@ -240,7 +240,7 @@ message Foo {
 After running Prototiller, the equivalent code might look like this:
 
 ```proto
-edition = "2023"
+edition = "2023";
 
 message Foo {
   message Bar {
@@ -275,7 +275,7 @@ for `repeated` fields has been migrated to in Editions.
 The following code sample shows a proto2 file:
 
 ```proto
-syntax = "proto2"
+syntax = "proto2";
 
 message Foo {
   repeated int32 bar = 6 [packed=true];
@@ -286,8 +286,8 @@ message Foo {
 After running Prototiller, the equivalent code might look like this:
 
 ```proto
-edition = "2023"
-options features.repeated_field_encoding = EXPANDED;
+edition = "2023";
+option features.repeated_field_encoding = EXPANDED;
 
 message Foo {
   repeated int32 bar = 6 [features.repeated_field_encoding=PACKED];
@@ -309,7 +309,7 @@ message Foo {
 After running Prototiller, the equivalent code might look like this:
 
 ```proto
-edition = "2023"
+edition = "2023";
 
 message Foo {
   repeated int32 bar = 6;
@@ -346,7 +346,7 @@ and after of a proto3 file.
 The following code sample shows a proto2 file:
 
 ```proto
-syntax = "proto2"
+syntax = "proto2";
 
 message MyMessage {
   string foo = 1;
@@ -356,7 +356,7 @@ message MyMessage {
 After running Prototiller, the equivalent code might look like this:
 
 ```proto
-edition = "2023"
+edition = "2023";
 
 message MyMessage {
   string foo = 1 [features.utf8_validation = NONE];
@@ -410,7 +410,7 @@ message Msg {
 After running Prototiller, the equivalent code might look like this:
 
 ```proto
-edition = "2023"
+edition = "2023";
 
 import "myproject/proto3file.proto";
 

content/editions/overview.md

@@ -19,7 +19,7 @@ message, field, enum, and so on, that specify the behavior of protoc, the code
 generators, and protobuf runtimes. You can explicitly override a behavior at
 those different levels (file, message, field, ...) when your needs don't match
 the default behavior for the edition you've selected. You can also override your
-overrides. The [section later in this topic on inheritance](#inheritance) goes
+overrides. The [section later in this topic on lexical scoping](#scoping) goes
 into more detail on that.
 
 ## Lifecycle of a Feature {#lifecycles}
@@ -202,16 +202,19 @@ message Player {
 
 </section>
 
-### Inheritance {#inheritance}
+<a name="inheritance"></a>
 
-Editions syntax supports inheritance, with a per-feature list of allowed
+### Lexical Scoping {#scoping}
+
+Editions syntax supports lexical scoping, with a per-feature list of allowed
 targets. For example, in the first edition, features can be specified at only
-the file level or the lowest level of granularity. Inheritance enables you to
-set the default behavior for a feature across an entire file, and then override
-that behavior at the message, field, enum, enum value, oneof, service, or
-method. Settings made at a higher level (file, message) apply when no setting is
-made within the same scope (field, enum value). Any features not explicitly set
-conform to the behavior defined in the edition version used for the .proto file.
+the file level or the lowest level of granularity. The implementation of lexical
+scoping enables you to set the default behavior for a feature across an entire
+file, and then override that behavior at the message, field, enum, enum value,
+oneof, service, or method level. Settings made at a higher level (file, message)
+apply when no setting is made within the same scope (field, enum value). Any
+features not explicitly set conform to the behavior defined in the edition
+version used for the .proto file.
 
 The following code sample shows some features being set at the file, message,
 and enum level. The settings are in the highlighted lines:
@@ -243,7 +246,7 @@ message Person {
 
 In the preceding example, the presence feature is set to `IMPLICIT`; it would
 default to `EXPLICIT` if it wasn't set. The `Pay_Type` `enum` will be `CLOSED`,
-as it inherits the file-level setting. The `Employment` `enum`, though, will be
+as it applies the file-level setting. The `Employment` `enum`, though, will be
 `OPEN`, as it is set within the enum.
 
 ### Prototiller {#prototiller}

content/getting-started/_index.md

@@ -1,3 +1,5 @@
+
+
 +++
 title = "Tutorials"
 weight = 200

content/news/2023-08-15.md

@@ -1,3 +1,5 @@
+
+
 +++
 title = "Changes Announced on August 15, 2023"
 linkTitle = "August 15, 2023"

content/programming-guides/extension_declarations.md

@@ -221,10 +221,15 @@ Deleting an extension declaration opens the door to accidental reuse in the
 future. If the extension is no longer processed and the definition is deleted,
 the extension declaration can be [marked reserved](#reserved).
 
-### Never Use a Field Number from the `reserved` List for a New Extension Declaration {#never-reuse-reserved}
+### Never Use a Field Name or Number from the `reserved` List for a New Extension Declaration {#never-reuse-reserved}
 
 Reserved numbers may have been used for fields or other extensions in the past.
 
+Using the `full_name` of a reserved field
+is not recommended
+due
+to the possibility of ambiguity when using textproto.
+
 ### Never change the type of an existing extension declaration {#never-change-type}
 
 Changing the extension field's type can result in data corruption.

content/programming-guides/proto3.md

@@ -244,8 +244,9 @@ from an input stream.
     message type, as well as a special `Builder` class for creating message
     class instances.
 *   For **Kotlin**, in addition to the Java generated code, the compiler
-    generates a `.kt` file for each message type, containing a DSL which can be
-    used to simplify creating message instances.
+    generates a `.kt` file for each message type with an improved Kotlin API.
+    This includes a DSL that simplifies creating message instances, a nullable
+    field accessor, and a copy function.
 *   **Python** is a little different — the Python compiler generates a module
     with a static descriptor of each message type in your `.proto`, which is
     then used with a *metaclass* to create the necessary Python data access
@@ -518,7 +519,8 @@ type-specific:
 *   For strings, the default value is the empty string.
 *   For bytes, the default value is empty bytes.
 *   For bools, the default value is false.
-*   For numeric types, the default value is zero.
+*   For numeric types, the default value is zero. For float and double types,
+    -0.0 and 0.0 are treated as equivalent, and will round-trip.
 *   For enums, the default value is the **first defined enum value**, which must
     be 0.
 *   For message fields, the field is not set. Its exact value is
@@ -534,7 +536,8 @@ whether a boolean was set to `false`) or just not set at all: you should bear
 this in mind when defining your message types. For example, don't have a boolean
 that switches on some behavior when set to `false` if you don't want that
 behavior to also happen by default. Also note that if a scalar message field
-**is** set to its default, the value will not be serialized on the wire.
+**is** set to its default, the value will not be serialized on the wire. If a
+float or double value is set to -0 or +0, it will not be serialized.
 
 See the [generated code guide](/reference/) for your
 chosen language for more details about how defaults work in generated code.
@@ -875,10 +878,8 @@ fields that the parser does not recognize. For example, when an old binary
 parses data sent by a new binary with new fields, those new fields become
 unknown fields in the old binary.
 
-Originally, proto3 messages always discarded unknown fields during parsing, but
-in version 3.5 we reintroduced the preservation of unknown fields to match the
-proto2 behavior. In versions 3.5 and later, unknown fields are retained during
-parsing and included in the serialized output.
+Proto3 messages preserve unknown fields and includes them during parsing and in
+the serialized output, which matches proto2 behavior.
 
 ## Any {#any}
 

content/reference/cpp/api-docs/_index.md

@@ -1,3 +1,5 @@
+
+
 +++
 title = "C++ Reference"
 toc_hide = "true"

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

@@ -1,3 +1,5 @@
+
+
 +++
 title = "arena.h"
 toc_hide = "true"

content/reference/cpp/api-docs/google.protobuf.compiler.ruby_generator.md

@@ -1,3 +1,5 @@
+
+
 +++
 title = "ruby_generator.h"
 toc_hide = "true"

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

@@ -1,3 +1,5 @@
+
+
 +++
 title = "dynamic_message.h"
 toc_hide = "true"