Merge pull request #157 from Logofile/main

Documentation updates

Author: Logofile

content/editions/features.md

@@ -57,7 +57,9 @@ overrides the message-scope QUUX setting.
 ### `features.enum_type` {#enum_type}
 
 This feature sets the behavior for how enum values that aren't contained within
-the defined set are handled.
+the defined set are handled. See
+[Enum Behavior](/programming-guides/enum) for more
+information on open and closed enums.
 
 This feature doesn't impact proto3 files, so this section doesn't have a before
 and after of a proto3 file.

content/programming-guides/dos-donts.md

@@ -109,52 +109,40 @@ using macro constants such as "`NULL`," "`NAN`," and "`DOMAIN`" as enum values.
 
 ## **Do** Use Well-Known Types and Common Types {#well-known-common}
 
-Embedding the following common, shared types is strongly encouraged. Do not use
-`int32 timestamp_seconds_since_epoch` or `int64 timeout_millis` in your code
+Using the following common, shared types is strongly encouraged. E.g., do not
+use `int32 timestamp_seconds_since_epoch` or `int64 timeout_millis` in your code
 when a perfectly suitable common type already exists!
 
-<a id="well-known-types"></a>
+<a id="well-known-types"></a><a id="common-types"></a>
 
-### Well-Known Types {#well-known}
-
-*   [duration](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/duration.proto)
+*   [`duration`](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/duration.proto)
     is a signed, fixed-length span of time (for example, 42s).
-*   [timestamp](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/timestamp.proto)
+*   [`timestamp`](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/timestamp.proto)
     is a point in time independent of any time zone or calendar (for example,
     2017-01-15T01:30:15.01Z).
-*   [field_mask](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/field_mask.proto)
-    is a set of symbolic field paths (for example, f.b.d).
-
-<a id="common-types"></a>
-
-### Common Types {#common}
-
-*   [`Duration`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/duration.proto)
-    is a signed, fixed-length span of time, such as 42s.
-*   [`Timestamp`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/timestamp.proto)
-    is a point in time independent of any time zone or calendar, such as
-    2017-01-15T01:30:15.01Z.
 *   [`interval`](https://github.com/googleapis/googleapis/blob/master/google/type/interval.proto)
     is a time interval independent of time zone or calendar (for example,
     2017-01-15T01:30:15.01Z - 2017-01-16T02:30:15.01Z).
 *   [`date`](https://github.com/googleapis/googleapis/blob/master/google/type/date.proto)
     is a whole calendar date (for example, 2005-09-19).
+*   [`month`](https://github.com/googleapis/googleapis/blob/master/google/type/month.proto)
+    is a month of year (for example, April).
 *   [`dayofweek`](https://github.com/googleapis/googleapis/blob/master/google/type/dayofweek.proto)
     is a day of week (for example, Monday).
 *   [`timeofday`](https://github.com/googleapis/googleapis/blob/master/google/type/timeofday.proto)
     is a time of day (for example, 10:42:23).
-*   [`latlng`](https://github.com/googleapis/googleapis/blob/master/google/type/latlng.proto)
-    is a latitude/longitude pair (for example, 37.386051 latitude and
-    -122.083855 longitude).
-*   [`money`](https://github.com/googleapis/googleapis/blob/master/google/type/money.proto)
-    is an amount of money with its currency type (for example, 42 USD).
+*   [`field_mask`](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/field_mask.proto)
+    is a set of symbolic field paths (for example, f.b.d).
 *   [`postal_address`](https://github.com/googleapis/googleapis/blob/master/google/type/postal_address.proto)
     is a postal address (for example, 1600 Amphitheatre Parkway Mountain View,
     CA 94043 USA).
+*   [`money`](https://github.com/googleapis/googleapis/blob/master/google/type/money.proto)
+    is an amount of money with its currency type (for example, 42 USD).
+*   [`latlng`](https://github.com/googleapis/googleapis/blob/master/google/type/latlng.proto)
+    is a latitude/longitude pair (for example, 37.386051 latitude and
+    -122.083855 longitude).
 *   [`color`](https://github.com/googleapis/googleapis/blob/master/google/type/color.proto)
     is a color in the RGBA color space.
-*   [`month`](https://github.com/googleapis/googleapis/blob/master/google/type/month.proto)
-    is a month of year (for example, April).
 
 <a id="do-define-widely-used-message-types-in-separate-files"></a>
 

content/programming-guides/proto2.md

@@ -228,19 +228,39 @@ number in the future.
 You should also reserve the field name to allow JSON and TextFormat encodings of
 your message to continue to parse.
 
-### Reserved Fields {#fieldreserved}
+<a id="fieldreserved"></a>
+
+### Reserved Field Numbers {#reserved-field-numbers}
 
 If you [update](#updating) a message type by entirely deleting a field, or
 commenting it out, future developers can reuse the field number when making
 their own updates to the type. This can cause severe issues, as described in
-[Consequences of Reusing Field Numbers](#consequences).
+[Consequences of Reusing Field Numbers](#consequences). To make sure this
+doesn't happen, add your deleted field number to the `reserved` list.
+
+The protoc compiler will generate error messages if any future developers try to
+use these reserved field numbers.
+
+```proto
+message Foo {
+  reserved 2, 15, 9 to 11;
+}
+```
+
+Reserved field number ranges are inclusive (`9 to 11` is the same as `9, 10,
+11`).
 
-To make sure this doesn't happen, add your deleted field number to the
-`reserved` list. To make sure JSON and TextFormat instances of your message can
-still be parsed, also add the deleted field name to a `reserved` list.
+#### Reserved Field Names {#reserved-field-names}
 
-The protocol buffer compiler will complain if any future developers try to use
-these reserved field numbers or names.
+Reusing an old field name later is generally safe, except when using TextProto
+or JSON encodings where the field name is serialized. To avoid this risk, you
+can add the deleted field name to the `reserved` list.
+
+Reserved names affect only the protoc compiler behavior and not runtime
+behavior, with one exception: TextProto implementations may discard unknown
+fields (without raising an error like with other unknown fields) with reserved
+names at parse time (only the C++ and Go implementations do so today). Runtime
+JSON parsing is not affected by reserved names.
 
 ```proto
 message Foo {
@@ -249,9 +269,8 @@ message Foo {
 }
 ```
 
-Reserved field number ranges are inclusive (`9 to 11` is the same as `9, 10,
-11`). Note that you can't mix field names and field numbers in the same
-`reserved` statement.
+Note that you can't mix field names and field numbers in the same `reserved`
+statement.
 
 ### What's Generated from Your `.proto`? {#generated}
 

content/programming-guides/proto3.md

@@ -205,19 +205,39 @@ the future.
 You should also reserve the field name to allow JSON and TextFormat encodings of
 your message to continue to parse.
 
-### Reserved Fields {#fieldreserved}
+<a id="fieldreserved"></a>
+
+#### Reserved Field Numbers {#reserved-field-numbers}
 
 If you [update](#updating) a message type by entirely deleting a field, or
 commenting it out, future developers can reuse the field number when making
 their own updates to the type. This can cause severe issues, as described in
-[Consequences of Reusing Field Numbers](#consequences).
+[Consequences of Reusing Field Numbers](#consequences). To make sure this
+doesn't happen, add your deleted field number to the `reserved` list.
+
+The protoc compiler will generate error messages if any future developers try to
+use these reserved field numbers.
+
+```proto
+message Foo {
+  reserved 2, 15, 9 to 11;
+}
+```
+
+Reserved field number ranges are inclusive (`9 to 11` is the same as `9, 10,
+11`).
 
-To make sure this doesn't happen, add your deleted field number to the
-`reserved` list. To make sure JSON and TextFormat instances of your message can
-still be parsed, also add the deleted field name to a `reserved` list.
+#### Reserved Field Names {#reserved-field-names}
 
-The protocol buffer compiler will complain if any future developers try to use
-these reserved field numbers or names.
+Reusing an old field name later is generally safe, except when using TextProto
+or JSON encodings where the field name is serialized. To avoid this risk, you
+can add the deleted field name to the `reserved` list.
+
+Reserved names affect only the protoc compiler behavior and not runtime
+behavior, with one exception: TextProto implementations may discard unknown
+fields (without raising an error like with other unknown fields) with reserved
+names at parse time (only the C++ and Go implementations do so today). Runtime
+JSON parsing is not affected by reserved names.
 
 ```proto
 message Foo {
@@ -226,9 +246,8 @@ message Foo {
 }
 ```
 
-Reserved field number ranges are inclusive (`9 to 11` is the same as `9, 10,
-11`). Note that you can't mix field names and field numbers in the same
-`reserved` statement.
+Note that you can't mix field names and field numbers in the same `reserved`
+statement.
 
 ### What's Generated from Your `.proto`? {#generated}
 

content/reference/other.md

@@ -25,6 +25,10 @@ We recommend that all third-party code generators be written as plugins, as this
 allows all generators to provide a consistent interface and share a single
 parser implementation.
 
+Plugins can be written in any programming language, but Google owned plugins are
+written in C++. If you are writing your own plugin you may find it easiest to
+use C++ for the plugin to be able to follow those examples and reuse utilities.
+
 Additionally, plugins are able to insert code into the files generated by other
 code generators. See the comments about \"insertion points\" in `plugin.proto`
 for more on this. This could be used, for example, to write a plugin which