Merge pull request #173 from Logofile/sync

Documentation update

Author: Logofile

content/getting-started/pythontutorial.md

@@ -209,17 +209,40 @@ descriptors for all your messages, enums, and fields, and some mysteriously
 empty classes, one for each message type:
 
 ```python
-class Person(message.Message):
-  __metaclass__ = reflection.GeneratedProtocolMessageType
-
-  class PhoneNumber(message.Message):
-    __metaclass__ = reflection.GeneratedProtocolMessageType
-    DESCRIPTOR = _PERSON_PHONENUMBER
-  DESCRIPTOR = _PERSON
-
-class AddressBook(message.Message):
-  __metaclass__ = reflection.GeneratedProtocolMessageType
-  DESCRIPTOR = _ADDRESSBOOK
+import google3
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.GOOGLE_INTERNAL,
+    0,
+    20240502,
+    0,
+    '',
+    'main.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\nmain.proto\x12\x08tutorial\"\xa3\x02\n\x06Person\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\n\n\x02id\x18\x02 \x01(\x05\x12\r\n\x05\x65mail\x18\x03 \x01(\t\x12,\n\x06phones\x18\x04 \x03(\x0b\x32\x1c.tutorial.Person.PhoneNumber\x1aX\n\x0bPhoneNumber\x12\x0e\n\x06number\x18\x01 \x01(\t\x12\x39\n\x04type\x18\x02 \x01(\x0e\x32\x1a.tutorial.Person.PhoneType:\x0fPHONE_TYPE_HOME\"h\n\tPhoneType\x12\x1a\n\x16PHONE_TYPE_UNSPECIFIED\x10\x00\x12\x15\n\x11PHONE_TYPE_MOBILE\x10\x01\x12\x13\n\x0fPHONE_TYPE_HOME\x10\x02\x12\x13\n\x0fPHONE_TYPE_WORK\x10\x03\"/\n\x0b\x41\x64\x64ressBook\x12 \n\x06people\x18\x01 \x03(\x0b\x32\x10.tutorial.Person')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'google3.main_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_PERSON']._serialized_start=25
+  _globals['_PERSON']._serialized_end=316
+  _globals['_PERSON_PHONENUMBER']._serialized_start=122
+  _globals['_PERSON_PHONENUMBER']._serialized_end=210
+  _globals['_PERSON_PHONETYPE']._serialized_start=212
+  _globals['_PERSON_PHONETYPE']._serialized_end=316
+  _globals['_ADDRESSBOOK']._serialized_start=318
+  _globals['_ADDRESSBOOK']._serialized_end=365
+# @@protoc_insertion_point(module_scope)
 ```
 
 The important line in each class is `__metaclass__ =

content/programming-guides/proto-limits.md

@@ -0,0 +1,49 @@
++++
+title = "Proto Limits"
+weight = 45
+description = "Covers the limits to number of supported elements in proto schemas."
+type = "docs"
++++
+
+This topic documents the limits to the number of supported elements (fields,
+enum values, and so on) in proto schemas.
+
+## Number of Fields {#fields}
+
+Message with only singular proto fields (such as Boolean):
+
+*   ~2100 fields (proto2)
+*   ~3100 (proto3 without using optional fields)
+
+Empty message extended by singular fields (such as Boolean):
+
+*   ~4100 fields (proto2)
+
+Extensions are supported
+[only by proto2](/programming-guides/version-comparison#extensionsany).
+
+To test this limitation, create a proto message with more than the upper bound
+number of fields and compile using a Java proto rule. The limit comes from JVM
+specs.
+
+## Number of Values in an Enum {#enum}
+
+The lowest limit is ~1700 values, in Java. Other languages have different
+limits.
+
+## Total Size of the Message {#total}
+
+Any proto in serialized form must be <2GiB, as that is the maximum size
+supported by all implementations. It's recommended to bound request and response
+sizes.
+
+## Depth Limit for Proto Unmarshaling {#depth}
+
+*   Java: 100
+*   C++: 100
+*   Go:
+    10000
+    (there is a plan to reduce this to 100)
+
+If you try to unmarshal a message that is nested deeper than the depth limit,
+the unmarshaling will fail.

content/programming-guides/proto2.md

@@ -947,6 +947,24 @@ 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.
 
+### Retaining Unknown Fields {#retaining}
+
+Some actions can cause unknown fields to be lost. For example, if you do one of
+the following, unknown fields are lost:
+
+*   Serialize a proto to JSON.
+*   Iterate over all of the fields in a message to populate a new message.
+
+To avoid losing unknown fields, do the following:
+
+*   Use binary; avoid using text formats for data exchange.
+*   Use message-oriented APIs, such as `CopyFrom()` and `MergeFrom()`, to copy data
+    rather than copying field-by-field
+
+TextFormat is a bit of a special case. Serializing to TextFormat prints unknown
+fields using their field numbers. But parsing TextFormat data back into a binary
+proto fails if there are entries that use field numbers.
+
 ## Extensions {#extensions}
 
 An extension is a field defined outside of its container message; usually in a

content/programming-guides/proto3.md

@@ -335,6 +335,7 @@ automatically generated class:
         <th>C# Type</th>
         <th>PHP Type</th>
         <th>Dart Type</th>
+        <th>Rust Type</th>
       </tr>
       <tr>
         <td>double</td>
@@ -347,6 +348,7 @@ automatically generated class:
         <td>double</td>
         <td>float</td>
         <td>double</td>
+        <td>f64</td>
       </tr>
       <tr>
         <td>float</td>
@@ -359,6 +361,7 @@ automatically generated class:
         <td>float</td>
         <td>float</td>
         <td>double</td>
+        <td>f32</td>
       </tr>
       <tr>
         <td>int32</td>
@@ -373,6 +376,7 @@ automatically generated class:
         <td>int</td>
         <td>integer</td>
         <td>int</td>
+        <td>i32</td>
       </tr>
       <tr>
         <td>int64</td>
@@ -387,6 +391,7 @@ automatically generated class:
         <td>long</td>
         <td>integer/string<sup>[6]</sup></td>
         <td>Int64</td>
+        <td>i64</td>
       </tr>
       <tr>
         <td>uint32</td>
@@ -399,6 +404,7 @@ automatically generated class:
         <td>uint</td>
         <td>integer</td>
         <td>int</td>
+        <td>u32</td>
       </tr>
       <tr>
         <td>uint64</td>
@@ -411,6 +417,7 @@ automatically generated class:
         <td>ulong</td>
         <td>integer/string<sup>[6]</sup></td>
         <td>Int64</td>
+        <td>u64</td>
       </tr>
       <tr>
         <td>sint32</td>
@@ -424,6 +431,7 @@ automatically generated class:
         <td>int</td>
         <td>integer</td>
         <td>int</td>
+        <td>i32</td>
       </tr>
       <tr>
         <td>sint64</td>
@@ -437,6 +445,7 @@ automatically generated class:
         <td>long</td>
         <td>integer/string<sup>[6]</sup></td>
         <td>Int64</td>
+        <td>i64</td>
       </tr>
       <tr>
         <td>fixed32</td>
@@ -450,6 +459,7 @@ automatically generated class:
         <td>uint</td>
         <td>integer</td>
         <td>int</td>
+        <td>u32</td>
       </tr>
       <tr>
         <td>fixed64</td>
@@ -463,6 +473,7 @@ automatically generated class:
         <td>ulong</td>
         <td>integer/string<sup>[6]</sup></td>
         <td>Int64</td>
+        <td>u64</td>
       </tr>
       <tr>
         <td>sfixed32</td>
@@ -475,6 +486,7 @@ automatically generated class:
         <td>int</td>
         <td>integer</td>
         <td>int</td>
+        <td>i32</td>
       </tr>
       <tr>
         <td>sfixed64</td>
@@ -487,6 +499,7 @@ automatically generated class:
         <td>long</td>
         <td>integer/string<sup>[6]</sup></td>
         <td>Int64</td>
+        <td>i64</td>
       </tr>
       <tr>
         <td>bool</td>
@@ -499,6 +512,7 @@ automatically generated class:
         <td>bool</td>
         <td>boolean</td>
         <td>bool</td>
+        <td>bool</td>
       </tr>
       <tr>
         <td>string</td>
@@ -512,6 +526,7 @@ automatically generated class:
         <td>string</td>
         <td>string</td>
         <td>String</td>
+        <td>ProtoString</td>
       </tr>
       <tr>
         <td>bytes</td>
@@ -524,6 +539,7 @@ automatically generated class:
         <td>ByteString</td>
         <td>string</td>
         <td>List<int></td>
+        <td>ProtoBytes</td>
       </tr>
     </tbody>
   </table>
@@ -925,6 +941,24 @@ unknown fields in the old binary.
 Proto3 messages preserve unknown fields and includes them during parsing and in
 the serialized output, which matches proto2 behavior.
 
+### Retaining Unknown Fields {#retaining}
+
+Some actions can cause unknown fields to be lost. For example, if you do one of
+the following, unknown fields are lost:
+
+*   Serialize a proto to JSON.
+*   Iterate over all of the fields in a message to populate a new message.
+
+To avoid losing unknown fields, do the following:
+
+*   Use binary; avoid using text formats for data exchange.
+*   Use message-oriented APIs, such as `CopyFrom()` and `MergeFrom()`, to copy data
+    rather than copying field-by-field
+
+TextFormat is a bit of a special case. Serializing to TextFormat prints unknown
+fields using their field numbers. But parsing TextFormat data back into a binary
+proto fails if there are entries that use field numbers.
+
 ## Any {#any}
 
 The `Any` message type lets you use messages as embedded types without having

content/reference/cpp/cpp-generated.md

@@ -249,10 +249,9 @@ corresponding C++ type according to the
 
 ### Implicit Presence Numeric Fields (proto3) {#implicit-numeric}
 
-For these field definitions:
+For the below field definition:
 
 ```proto
-optional int32 foo = 1;
 int32 foo = 1;  // no field label specified, defaults to implicit presence.
 ```
 
@@ -322,12 +321,10 @@ The compiler will generate the following accessor methods:
 
 ### Implicit Presence String/Bytes Fields (proto3) {#implicit-string}
 
-For any of these field definitions:
+For either of these field definitions:
 
 ```proto
-optional string foo = 1;
 string foo = 1;  // no field label specified, defaults to implicit presence.
-optional bytes foo = 1;
 bytes foo = 1;
 ```
 
@@ -440,10 +437,9 @@ enum Bar {
 }
 ```
 
-For these field definitions:
+For this field definition:
 
 ```proto
-optional Bar foo = 1;
 Bar foo = 1;  // no field label specified, defaults to implicit presence.
 ```