Merge pull request #178 from Logofile/sync

Documentation update

content/getting-started/pythontutorial.md

@@ -189,7 +189,7 @@ compiler `protoc` on your `.proto`:
     `.proto`. In this case, you...:
 
     ```shell
-    protoc -I=$SRC_DIR --python_out=$DST_DIR $SRC_DIR/addressbook.proto
+    protoc --proto_path=$SRC_DIR --python_out=$DST_DIR $SRC_DIR/addressbook.proto
     ```
 
     Because you want Python classes, you use the `--python_out` option --

content/programming-guides/enum.md

@@ -103,6 +103,17 @@ behave.
 
 All known C++ releases are out of conformance. When a `proto2` file imports an
 enum defined in a `proto3` file, C++ treats that field as a **closed** enum.
+Under editions, this behavior is represented by the deprecated field feature
+[`features.(pb.cpp).legacy_closed_enum`](/editions/features#legacy_closed_enum).
+There are two options for moving to conformant behavior:
+
+*   Remove the field feature. This is the recommended approach, but may cause
+    runtime behavior changes. Without the feature, unrecognized integers will
+    end up stored in the field cast to the enum type instead of being put into
+    the unknown field set.
+*   Change the enum to closed. This is discouraged, and can cause runtime
+    behavior if *anybody else* is using the enum. Unrecognized integers will end
+    up in the unknown field set instead of those fields.
 
 ### C# {#csharp}
 
@@ -113,6 +124,18 @@ All known C# releases are out of conformance. C# treats all enums as **open**.
 All known Java releases are out of conformance. When a `proto2` file imports an
 enum defined in a `proto3` file, Java treats that field as a **closed** enum.
 
+Under editions, this behavior is represented by the deprecated field feature
+[`features.(pb.java).legacy_closed_enum`](/editions/features#legacy_closed_enum)).
+There are two options for moving to conformant behavior:
+
+*   Remove the field feature. This may cause runtime behavior changes. Without
+    the feature, unrecognized integers will end up stored in the field and the
+    `UNRECOGNIZED` value will be returned by the enum getter. Before, these
+    values would be put into the unknown field set.
+*   Change the enum to closed. If *anybody else* is using it they may see
+    runtime behavior changes. Unrecognized integers will end up in the unknown
+    field set instead of those fields.
+
 > **NOTE:** Java's handling of **open** enums has surprising edge cases. Given
 > the following definitions:
 >

content/programming-guides/proto-limits.md

@@ -44,8 +44,10 @@ sizes.
 
 ## Depth Limit for Proto Unmarshaling {#depth}
 
-*   Java: 100
-*   C++: 100
+*   Java:
+    100
+*   C++:
+    100
 *   Go:
     10000
     (there is a plan to reduce this to 100)

content/programming-guides/proto2.md

@@ -634,8 +634,9 @@ symbolic constants with integer values in the runtime-generated class.
 
 {{% alert title="Important" color="warning" %}} The
 generated code may be subject to language-specific limitations on the number of
-enumerators (low thousands for one language). Review the limitations for the
-languages you plan to use. {{% /alert %}}
+enumerators (low thousands for one language). Review the
+limitations for the languages you plan to use.
+{{% /alert %}}
 
 {{% alert title="Important" color="warning" %}} For
 information on how enums should work contrasted with how they currently work in

content/programming-guides/proto3.md

@@ -684,8 +684,9 @@ symbolic constants with integer values in the runtime-generated class.
 
 {{% alert title="Important" color="warning" %}} The
 generated code may be subject to language-specific limitations on the number of
-enumerators (low thousands for one language). Review the limitations for the
-languages you plan to use. {{% /alert %}}
+enumerators (low thousands for one language). Review the
+limitations for the languages you plan to use.
+{{% /alert %}}
 
 During deserialization, unrecognized enum values will be preserved in the
 message, though how this is represented when the message is deserialized is

content/reference/java/java-generated.md

@@ -205,7 +205,8 @@ implements the `Message.Builder` interface. It extends the
 `GeneratedMessage.Builder` class, but, again, this should be considered an
 implementation detail. Like `Foo`, `Foo.Builder` may rely on generic method
 implementations in `GeneratedMessage.Builder` or, when the `optimize_for` option
-is used, generated custom code that is much faster.
+is used, generated custom code that is much faster. You can get a `Foo.Builder`
+by calling the static method `Foo.newBuilder()`.
 
 `Foo.Builder` does not define any static methods. Its interface is exactly as
 defined by the `Message.Builder` interface, with the exception that return types

content/reference/ruby/ruby-generated.md

@@ -357,12 +357,12 @@ end
 
 An enum module also defines the following utility methods:
 
--   `Enum#lookup(number)`: Looks up the given number and returns its name, or
-    `nil` if none was found. If more than one name has this number, returns the
-    first that was defined.
--   `Enum#resolve(symbol)`: Returns the number for this enum name, or `nil` if
-    none was found.
--   `Enum#descriptor`: Returns the descriptor for this enum.
+-   `Foo::SomeEnum.lookup(number)`: Looks up the given number and returns its
+    name, or `nil` if none was found. If more than one name has this number,
+    returns the first that was defined.
+-   `Foo::SomeEnum.resolve(symbol)`: Returns the number for this enum name, or
+    `nil` if none was found.
+-   `Foo::SomeEnum.descriptor`: Returns the descriptor for this enum.
 
 ## Oneof