Merge pull request #161 from Logofile/sync

Documentation change

Author: Logofile

content/_index.md

@@ -7,20 +7,21 @@ type = "docs"
 no_list = "true"
 +++
 
-<!--* css: "//depot/includes/suppress-nav.css" *-->
+## What Are Protocol Buffers?
 
-<style>
-.row .highlight {
-    margin-top: 2rem;
-    margin-right: 0;
-    margin-bottom: 0;
-    margin-left: 0;
-    padding: 0;
-}
-</style>
+Protocol buffers are Google's language-neutral, platform-neutral, extensible
+mechanism for serializing structured data – think XML, but smaller, faster, and
+simpler. You define how you want your data to be structured once, then you can
+use special generated source code to easily write and read your structured data
+to and from a variety of data streams and using a variety of languages.
+
+## Pick Your Favorite Language
+
+Protocol buffers support generated code in C++, C#, Dart, Go, Java,
+Kotlin,
+Objective-C, Python, and Ruby. With proto3, you can also work with PHP.
 
-<div class="row">
-<div class="col-md">
+## Example Implementation
 
 ```proto
 message Person {
@@ -30,9 +31,7 @@ message Person {
 }
 ```
 
-<p class="caption">A proto definition.</>
-</div>
-<div class="col-md">
+**Figure 1.** A proto definition.
 
 ```java
 // Java code
@@ -43,12 +42,9 @@ Person john = Person.newBuilder()
     .build();
 output = new FileOutputStream(args[0]);
 john.writeTo(output);
-
 ```
 
-<p class="caption">Using a generated class to persist data.</p>
-</div>
-<div class="col-md">
+**Figure 2.** Using a generated class to persist data.
 
 ```cpp
 // C++ code
@@ -59,34 +55,9 @@ john.ParseFromIstream(&input);
 id = john.id();
 name = john.name();
 email = john.email();
-
 ```
 
-<p class="caption">Using a generated class to parse persisted data.</p>
-</div>
-</div>
-<div class="row">
-<div class="col-md">
-
-## What Are Protocol Buffers?
-
-Protocol buffers are Google's language-neutral, platform-neutral, extensible
-mechanism for serializing structured data – think XML, but smaller, faster, and
-simpler. You define how you want your data to be structured once, then you can
-use special generated source code to easily write and read your structured data
-to and from a variety of data streams and using a variety of languages.
-
-</div>
-<div class="col-md">
-
-## Pick Your Favorite Language
-
-Protocol buffers support generated code in C++, C#, Dart, Go, Java,
-Kotlin,
-Objective-C, Python, and Ruby. With proto3, you can also work with PHP.
-
-</div>
-<div class="col-md">
+**Figure 3.** Using a generated class to parse persisted data.
 
 ## How Do I Start?
 
@@ -106,6 +77,3 @@ Objective-C, Python, and Ruby. With proto3, you can also work with PHP.
     chosen language.
   </li>
 </ol>
-
-</div>
-</div>

content/editions/features.md

@@ -285,7 +285,7 @@ edition = "2023";
 
 message Foo {
   message Bar {
-    optional int32 x = 1;
+    int32 x = 1;
     repeated int32 y = 2;
   }
   Bar bar = 1 [features.message_encoding = DELIMITED];
@@ -509,8 +509,8 @@ edition = "2023";
 import "google/protobuf/cpp_features.proto";
 
 message Foo {
-  optional string bar = 6;
-  optional string baz = 7 [features.(pb.cpp).string_type = CORD];
+  string bar = 6;
+  string baz = 7 [features.(pb.cpp).string_type = CORD];
 }
 ```
 

content/editions/overview.md

@@ -9,7 +9,7 @@ type = "docs"
 Protobuf Editions replace the proto2 and proto3 designations that we have used
 for Protocol Buffers. Instead of adding `syntax = "proto2"` or `syntax =
 "proto3"` at the top of proto definition files, you use an edition number, such
-as `edition = "2024"`, to specify the default behaviors your file will have.
+as `edition = "2023"`, to specify the default behaviors your file will have.
 Editions enable the language to evolve incrementally over time.
 
 Instead of the hardcoded behaviors that older versions have had, editions
@@ -22,6 +22,8 @@ the default behavior for the edition you've selected. You can also override your
 overrides. The [section later in this topic on lexical scoping](#scoping) goes
 into more detail on that.
 
+*The latest released edition is 2023.*
+
 ## Lifecycle of a Feature {#lifecycles}
 
 Editions provide the fundamental increments for the lifecycle of a feature.
@@ -93,6 +95,8 @@ Prototiller tool to change the definition files to use Protobuf Editions syntax.
 // proto2 file
 syntax = "proto2";
 
+package com.example;
+
 message Player {
   // in proto2, optional fields have explicit presence
   optional string name = 1;
@@ -110,6 +114,8 @@ message Player {
 
   // in proto2 enums are closed
   optional Handed handed = 4;
+
+  reserved "gender";
 }
 ```
 
@@ -119,6 +125,8 @@ message Player {
 // Edition version of proto2 file
 edition = "2023";
 
+package com.example;
+
 message Player {
   // fields have explicit presence, so no explicit setting needed
   string name = 1;
@@ -137,6 +145,8 @@ message Player {
   }
 
   Handed handed = 4;
+
+  reserved gender;
 }
 ```
 
@@ -155,6 +165,8 @@ Prototiller tool to change the definition files to use Protobuf Editions syntax.
 // proto3 file
 syntax = "proto3";
 
+package com.example;
+
 message Player {
   // in proto3, optional fields have explicit presence
   optional string name = 1;
@@ -172,6 +184,8 @@ message Player {
 
   // in proto3 enums are open
   optional Handed handed = 4;
+
+  reserved "gender";
 }
 ```
 
@@ -181,6 +195,8 @@ message Player {
 // Editions version of proto3 file
 edition = "2023";
 
+package com.example;
+
 message Player {
   // fields have explicit presence, so no explicit setting needed
   string name = 1;
@@ -197,6 +213,8 @@ message Player {
   }
 
   Handed handed = 4;
+
+  reserved gender;
 }
 ```
 
@@ -229,16 +247,16 @@ message Person {
   int32 id = 2 [features.presence = IMPLICIT];
 
   enum Pay_Type {
-    PAY_TYPE_UNSPECIFIED = 1,
-    PAY_TYPE_SALARY = 2,
-    PAY_TYPE_HOURLY = 3
+    PAY_TYPE_UNSPECIFIED = 1;
+    PAY_TYPE_SALARY = 2;
+    PAY_TYPE_HOURLY = 3;
   }
 
   enum Employment {
     option features.enum_type = OPEN;
-    EMPLOYMENT_UNSPECIFIED = 0,
-    EMPLOYMENT_FULLTIME = 1,
-    EMPLOYMENT_PARTTIME = 2,
+    EMPLOYMENT_UNSPECIFIED = 0;
+    EMPLOYMENT_FULLTIME = 1;
+    EMPLOYMENT_PARTTIME = 2;
   }
   Employment employment = 4;
 }
@@ -270,9 +288,9 @@ definition files, and vice versa:
 syntax = "proto2";
 
 enum Employment {
-  EMPLOYMENT_UNSPECIFIED = 0,
-  EMPLOYMENT_FULLTIME = 1,
-  EMPLOYMENT_PARTTIME = 2,
+  EMPLOYMENT_UNSPECIFIED = 0;
+  EMPLOYMENT_FULLTIME = 1;
+  EMPLOYMENT_PARTTIME = 2;
 }
 ```
 

content/getting-started/gotutorial.md

@@ -232,7 +232,7 @@ p := pb.Person{
     Name:  "John Doe",
     Email: "jdoe@example.com",
     Phones: []*pb.Person_PhoneNumber{
-        {Number: "555-4321", Type: pb.Person_PHONE_TYPE_HOME},
+        {Number: "555-4321", Type: pb.PhoneType_PHONE_TYPE_HOME},
     },
 }
 ```

content/overview.md

@@ -305,3 +305,4 @@ protobuf developers and users,
 ## Additional Resources {#additional-resources}
 
 *   [Protocol Buffers GitHub](https://github.com/protocolbuffers/protobuf/)
+*   [Codelabs](/getting-started/codelabs)

content/programming-guides/dos-donts.md

@@ -196,6 +196,9 @@ For example:
     https://google.github.io/styleguide/cppguide.html#Namespace_Names.
     If these style guides conflict, use `java_package` for Java.
 
+*   `ruby_package` should be in the form `Foo::Bar::Baz` rather than
+    `Foo.Bar.Baz`.
+
 <a id="never-use-text-format-messages-for-interchange"></a>
 
 ## **Don't** use Text Format Messages for Interchange {#text-format-interchange}

content/programming-guides/enum.md

@@ -49,7 +49,7 @@ question:
 
 ## Implications of *Closed* Enums
 
-The behavior of *closed* enums has unexpected consquences when parsing a
+The behavior of *closed* enums has unexpected consequences when parsing a
 repeated field. When a `repeated Enum` field is parsed all unknown values will
 be placed in the
 [unknown field](/programming-guides/proto3/#unknowns)

content/programming-guides/field_presence.md

@@ -157,13 +157,13 @@ for generated APIs and using dynamic reflection):
 Field type                                   | `optional` | Explicit Presence
 -------------------------------------------- | ---------- | -----------------
 Singular numeric (integer or floating point) | No         |
-Singular enum                                | No         |
-Singular string or bytes                     | No         |
 Singular numeric (integer or floating point) | Yes        | ✔️
+Singular enum                                | No         |
 Singular enum                                | Yes        | ✔️
+Singular string or bytes                     | No         |
 Singular string or bytes                     | Yes        | ✔️
-Singular message                             | Yes        | ✔️
 Singular message                             | No         | ✔️
+Singular message                             | Yes        | ✔️
 Repeated                                     | N/A        |
 Oneofs                                       | N/A        | ✔️
 Maps                                         | N/A        |

content/programming-guides/proto2.md

@@ -1939,8 +1939,8 @@ Here are a few of the most commonly used options:
         message types. This code is highly optimized.
     *   `CODE_SIZE`: The protocol buffer compiler will generate minimal classes
         and will rely on shared, reflection-based code to implement
-        serialialization, parsing, and various other operations. The generated
-        code will thus be much smaller than with `SPEED`, but operations will be
+        serialization, parsing, and various other operations. The generated code
+        will thus be much smaller than with `SPEED`, but operations will be
         slower. Classes will still implement exactly the same public API as they
         do in `SPEED` mode. This mode is most useful in apps that contain a very
         large number of `.proto` files and do not need all of them to be

content/programming-guides/proto3.md

@@ -1487,8 +1487,8 @@ Here are a few of the most commonly used options:
         message types. This code is highly optimized.
     *   `CODE_SIZE`: The protocol buffer compiler will generate minimal classes
         and will rely on shared, reflection-based code to implement
-        serialialization, parsing, and various other operations. The generated
-        code will thus be much smaller than with `SPEED`, but operations will be
+        serialization, parsing, and various other operations. The generated code
+        will thus be much smaller than with `SPEED`, but operations will be
         slower. Classes will still implement exactly the same public API as they
         do in `SPEED` mode. This mode is most useful in apps that contain a very
         large number of `.proto` files and do not need all of them to be