This documentation changes includes the following:

* Moves best practices topics into a subsection
* Fixes formatting for Notes and Warnings
* Adds default-value syntax to the examples in the overview topic
* Updates the C++ types in the scalar values tables
* Updates the Arenas topic to reflect the replacement of `CreateMessage()` with `Create()`
* Corrects the package section in the Java Generated topic
* Updates the proto3 spec to add the `optional` field type modifier

PiperOrigin-RevId: 710759644
Change-Id: I44fa6fe46103003f12f64dfa06dc58758cd638cd

Author: Protocol Buffer Team

eng/doc/devguide/proto/best-practices/1-1-1.md renamed to content/best-practices/1-1-1.md

@@ -188,11 +188,12 @@ language-appropriate naming:
     delimited encoding
 *   `EnumDescriptor::is_closed` - Whether or not a field is closed
 
-**Note:** In most languages, the message encoding feature is still currently
-signaled by `TYPE_GROUP` and required fields still have `LABEL_REQUIRED` set.
-This is not ideal, and was done to make downstream migrations easier.
-Eventually, these should be migrated to the appropriate helpers and
-`TYPE_MESSAGE/LABEL_OPTIONAL`.
+{{% alert title="Note" color="note" %}} In
+most languages, the message encoding feature is still currently signaled by
+`TYPE_GROUP` and required fields still have `LABEL_REQUIRED` set. This is not
+ideal, and was done to make downstream migrations easier. Eventually, these
+should be migrated to the appropriate helpers and
+`TYPE_MESSAGE/LABEL_OPTIONAL`.{{% /alert %}}
 
 Downstream users should migrate to these new helpers instead of using syntax
 directly. The following class of existing descriptor APIs should ideally be

eng/doc/devguide/proto/best-practices/index.md renamed to content/best-practices/_index.md

@@ -99,7 +99,7 @@ package com.example;
 
 message Player {
   // in proto2, optional fields have explicit presence
-  optional string name = 1;
+  optional string name = 1 [default = "N/A"];
   // proto2 still supports the problematic "required" field rule
   required int32 id = 2;
   // in proto2 this is not packed by default
@@ -129,7 +129,7 @@ package com.example;
 
 message Player {
   // fields have explicit presence, so no explicit setting needed
-  string name = 1;
+  string name = 1 [default = "N/A"];
   // to match the proto2 behavior, LEGACY_REQUIRED is set at the field level
   int32 id = 2 [features.field_presence = LEGACY_REQUIRED];
   // to match the proto2 behavior, EXPANDED is set at the field level
@@ -169,7 +169,7 @@ package com.example;
 
 message Player {
   // in proto3, optional fields have explicit presence
-  optional string name = 1;
+  optional string name = 1 [default = "N/A"];
   // in proto3 no specified field rule defaults to implicit presence
   int32 id = 2;
   // in proto3 this is packed by default
@@ -199,7 +199,7 @@ package com.example;
 
 message Player {
   // fields have explicit presence, so no explicit setting needed
-  string name = 1;
+  string name = 1 [default = "N/A"];
   // to match the proto3 behavior, IMPLICIT is set at the field level
   int32 id = 2 [features.field_presence = IMPLICIT];
   // PACKED is the default state, and is provided just for illustration

eng/doc/devguide/proto/best-practices/api.md renamed to content/best-practices/api.md

@@ -376,7 +376,7 @@ automatically generated class:
         <td>Uses variable-length encoding. Inefficient for encoding negative
         numbers – if your field is likely to have negative values, use sint32
         instead.</td>
-        <td>int32</td>
+        <td>int32_t</td>
         <td>int</td>
         <td>int</td>
         <td>int32</td>
@@ -391,7 +391,7 @@ automatically generated class:
         <td>Uses variable-length encoding. Inefficient for encoding negative
         numbers – if your field is likely to have negative values, use sint64
         instead.</td>
-        <td>int64</td>
+        <td>int64_t</td>
         <td>long</td>
         <td>int/long<sup>[4]</sup></td>
         <td>int64</td>
@@ -404,7 +404,7 @@ automatically generated class:
       <tr>
         <td>uint32</td>
         <td>Uses variable-length encoding.</td>
-        <td>uint32</td>
+        <td>uint32_t</td>
         <td>int<sup>[2]</sup></td>
         <td>int/long<sup>[4]</sup></td>
         <td>uint32</td>
@@ -417,7 +417,7 @@ automatically generated class:
       <tr>
         <td>uint64</td>
         <td>Uses variable-length encoding.</td>
-        <td>uint64</td>
+        <td>uint64_t</td>
         <td>long<sup>[2]</sup></td>
         <td>int/long<sup>[4]</sup></td>
         <td>uint64</td>
@@ -431,7 +431,7 @@ automatically generated class:
         <td>sint32</td>
         <td>Uses variable-length encoding. Signed int value. These more
         efficiently encode negative numbers than regular int32s.</td>
-        <td>int32</td>
+        <td>int32_t</td>
         <td>int</td>
         <td>int</td>
         <td>int32</td>
@@ -445,7 +445,7 @@ automatically generated class:
         <td>sint64</td>
         <td>Uses variable-length encoding. Signed int value. These more
         efficiently encode negative numbers than regular int64s.</td>
-        <td>int64</td>
+        <td>int64_t</td>
         <td>long</td>
         <td>int/long<sup>[4]</sup></td>
         <td>int64</td>
@@ -459,7 +459,7 @@ automatically generated class:
         <td>fixed32</td>
         <td>Always four bytes. More efficient than uint32 if values are often
         greater than 2<sup>28</sup>.</td>
-        <td>uint32</td>
+        <td>uint32_t</td>
         <td>int<sup>[2]</sup></td>
         <td>int/long<sup>[4]</sup></td>
         <td>uint32</td>
@@ -473,7 +473,7 @@ automatically generated class:
         <td>fixed64</td>
         <td>Always eight bytes. More efficient than uint64 if values are often
         greater than 2<sup>56</sup>.</td>
-        <td>uint64</td>
+        <td>uint64_t</td>
         <td>long<sup>[2]</sup></td>
         <td>int/long<sup>[4]</sup></td>
         <td>uint64</td>
@@ -486,7 +486,7 @@ automatically generated class:
       <tr>
         <td>sfixed32</td>
         <td>Always four bytes.</td>
-        <td>int32</td>
+        <td>int32_t</td>
         <td>int</td>
         <td>int</td>
         <td>int32</td>
@@ -499,7 +499,7 @@ automatically generated class:
       <tr>
         <td>sfixed64</td>
         <td>Always eight bytes.</td>
-        <td>int64</td>
+        <td>int64_t</td>
         <td>long</td>
         <td>int/long<sup>[4]</sup></td>
         <td>int64</td>
@@ -696,8 +696,8 @@ field default.
 You can define aliases by assigning the same value to different enum constants.
 To do this you need to set the `allow_alias` option to `true`. Otherwise, the
 protocol buffer compiler generates a warning message when aliases are
-found. Though all alias values are valid during deserialization, the first value
-is always used when serializing.
+found. Though all alias values are valid for serialization, only the first value
+is used when deserializing.
 
 ```proto
 enum EnumAllowingAlias {
@@ -716,6 +716,8 @@ enum EnumNotAllowingAlias {
 }
 ```
 
+### Enum Constants {#enum-constants}
+
 Enumerator constants must be in the range of a 32-bit integer. Since `enum`
 values use
 [varint encoding](/programming-guides/encoding) on the
@@ -725,6 +727,8 @@ these `enum`s can be reused in any message definition in your `.proto` file. You
 can also use an `enum` type declared in one message as the type of a field in a
 different message, using the syntax `_MessageType_._EnumType_`.
 
+### Language-specific Enum Implementations {#enum-language}
+
 When you run the protocol buffer compiler on a `.proto` that uses an `enum`, the
 generated code will have a corresponding `enum` for Java, Kotlin, or C++, or a
 special `EnumDescriptor` class for Python that's used to create a set of

eng/doc/devguide/proto/best-practices/dos-donts.md renamed to content/best-practices/dos-donts.md

@@ -15,9 +15,11 @@ freshness: { owner: 'shaod' reviewed: '2024-09-16' }
 This page describes in detail what extension declarations are, why we need them,
 and how we use them.
 
-**NOTE:** Proto3 does not support extensions (except for
+{{% alert title="Note" color="note" %}}
+Proto3 does not support extensions (except for
 [declaring custom options](/programming-guides/proto3/#customoptions)).
-Extensions are fully supported in proto2 and editions though.
+Extensions are fully supported in proto2 and editions
+though.{{% /alert %}}
 
 If you need an introduction to extensions, read this
 [extensions guide](https://protobuf.dev/programming-guides/proto2/#extensions)
@@ -74,9 +76,11 @@ This syntax has the following semantics:
     (`Foo`) with this name or number, we enforce that the number, type, and full
     name of the extension match what is forward-declared here.
 
-**WARNING:** Avoid using declarations for extension range groups such as
-`extensions 4, 999`. It is unclear which extension range the declarations apply
-to, and it is currently unsupported.
+{{% alert title="Warning" color="warning" %}}
+Avoid using declarations for extension range groups such as `extensions 4, 999`.
+It is unclear which extension range the declarations apply to, and it is
+currently
+unsupported.{{% /alert %}}
 
 The extension declarations expect two extension fields with different packages:
 

content/editions/implementation.md

@@ -19,9 +19,10 @@ types (numeric, string, bytes, and enums) which are defined with the `optional`
 label have *explicit presence*, like proto2 (this feature is enabled by default
 as release 3.15).
 
-**NOTE:** We recommend always adding the `optional` label for proto3 basic
-types. This provides a smoother path to editions, which uses explicit presence
-by default.
+{{% alert title="Note" color="note" %}} We
+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
 
@@ -214,9 +215,10 @@ For a singular field with numeric, enum, or string type:
     -   A generated `clear_foo` method must be used to clear (i.e., un-set) the
         value.
 
-**Note:** `Has_` methods are not generated for implicit members in most cases.
-The exception to this behavior is Dart, which generates `has_` methods with
-proto3 proto schema files.
+{{% alert title="Note" color="note" %}}
+`Has_` methods are not generated for implicit members in most cases. The
+exception to this behavior is Dart, which generates `has_` methods with proto3
+proto schema files.{{% /alert %}}
 
 ### Considerations for Merging
 

content/editions/overview.md

@@ -406,7 +406,7 @@ automatically generated class:
         <td>Uses variable-length encoding. Inefficient for encoding negative
         numbers – if your field is likely to have negative values, use sint32
         instead.</td>
-        <td>int32</td>
+        <td>int32_t</td>
         <td>int</td>
         <td>int</td>
         <td>int32</td>
@@ -421,7 +421,7 @@ automatically generated class:
         <td>Uses variable-length encoding. Inefficient for encoding negative
         numbers – if your field is likely to have negative values, use sint64
         instead.</td>
-        <td>int64</td>
+        <td>int64_t</td>
         <td>long</td>
         <td>int/long<sup>[4]</sup></td>
         <td>*int64</td>
@@ -434,7 +434,7 @@ automatically generated class:
       <tr>
         <td>uint32</td>
         <td>Uses variable-length encoding.</td>
-        <td>uint32</td>
+        <td>uint32_t</td>
         <td>int<sup>[2]</sup></td>
         <td>int/long<sup>[4]</sup></td>
         <td>*uint32</td>
@@ -447,7 +447,7 @@ automatically generated class:
       <tr>
         <td>uint64</td>
         <td>Uses variable-length encoding.</td>
-        <td>uint64</td>
+        <td>uint64_t</td>
         <td>long<sup>[2]</sup></td>
         <td>int/long<sup>[4]</sup></td>
         <td>*uint64</td>
@@ -461,7 +461,7 @@ automatically generated class:
         <td>sint32</td>
         <td>Uses variable-length encoding. Signed int value. These more
         efficiently encode negative numbers than regular int32s.</td>
-        <td>int32</td>
+        <td>int32_t</td>
         <td>int</td>
         <td>int</td>
         <td>int32</td>
@@ -475,7 +475,7 @@ automatically generated class:
         <td>sint64</td>
         <td>Uses variable-length encoding. Signed int value. These more
         efficiently encode negative numbers than regular int64s.</td>
-        <td>int64</td>
+        <td>int64_t</td>
         <td>long</td>
         <td>int/long<sup>[4]</sup></td>
         <td>*int64</td>
@@ -489,7 +489,7 @@ automatically generated class:
         <td>fixed32</td>
         <td>Always four bytes. More efficient than uint32 if values are often
         greater than 2<sup>28</sup>.</td>
-        <td>uint32</td>
+        <td>uint32_t</td>
         <td>int<sup>[2]</sup></td>
         <td>int/long<sup>[4]</sup></td>
         <td>*uint32</td>
@@ -503,7 +503,7 @@ automatically generated class:
         <td>fixed64</td>
         <td>Always eight bytes. More efficient than uint64 if values are often
         greater than 2<sup>56</sup>.</td>
-        <td>uint64</td>
+        <td>uint64_t</td>
         <td>long<sup>[2]</sup></td>
         <td>int/long<sup>[4]</sup></td>
         <td>*uint64</td>
@@ -516,7 +516,7 @@ automatically generated class:
       <tr>
         <td>sfixed32</td>
         <td>Always four bytes.</td>
-        <td>int32</td>
+        <td>int32_t</td>
         <td>int</td>
         <td>int</td>
         <td>*int32</td>
@@ -529,7 +529,7 @@ automatically generated class:
       <tr>
         <td>sfixed64</td>
         <td>Always eight bytes.</td>
-        <td>int64</td>
+        <td>int64_t</td>
         <td>long</td>
         <td>int/long<sup>[4]</sup></td>
         <td>*int64</td>