From d75b49a09168103d132dcccf7dc9d6e126ba1f98 Mon Sep 17 00:00:00 2001 From: Protobuf Team Bot Date: Thu, 8 Oct 2026 06:34:18 -0700 Subject: [PATCH] Use 'Protobuf' as the proper noun of our project. The name 'Protocol Buffers' is relegated to a parenthetical on the landing page. Words like 'Protobufs', 'Protobuffs', 'Protobuffers' are excised. PiperOrigin-RevId: 995798173 --- content/_index.md | 25 +-- content/best-practices/1-1-1.md | 2 +- content/best-practices/dos-donts.md | 14 +- content/downloads.md | 6 +- content/editions/features.md | 10 +- content/editions/overview.md | 14 +- content/getting-started/_index.md | 8 +- content/getting-started/cpptutorial.md | 151 +++++++------- content/getting-started/csharptutorial.md | 90 ++++----- content/getting-started/darttutorial.md | 87 ++++---- content/getting-started/gotutorial.md | 89 ++++----- content/getting-started/javatutorial.md | 121 ++++++------ content/getting-started/kotlintutorial.md | 95 +++++---- content/getting-started/pythontutorial.md | 116 +++++------ content/history.md | 77 ++++---- content/installation.md | 8 +- content/news/2022-05-06.md | 24 +-- content/news/2022-07-06.md | 6 +- content/news/2022-08-03.md | 12 +- content/news/2023-04-11.md | 2 +- content/news/2023-04-20.md | 2 +- content/news/2023-04-28.md | 2 +- content/news/2023-06-29.md | 12 +- content/news/2023-07-06.md | 4 +- content/news/2023-07-17.md | 2 +- content/news/2023-08-09.md | 2 +- content/news/2023-08-15.md | 2 +- content/news/2023-09-15.md | 10 +- content/news/2023-10-10.md | 2 +- content/news/2023-12-05.md | 8 +- content/news/2023-12-13.md | 8 +- content/news/2023-12-27.md | 2 +- content/news/2024-01-05.md | 2 +- content/news/2024-01-31.md | 2 +- content/news/2024-02-05.md | 2 +- content/news/2024-02-27.md | 2 +- content/news/2024-06-26.md | 4 +- content/news/2024-10-01.md | 16 +- content/news/2024-10-02.md | 2 +- content/news/2024-11-07.md | 12 +- content/news/2024-12-04.md | 2 +- content/news/2024-12-13.md | 2 +- content/news/2024-12-18.md | 6 +- content/news/2025-01-23.md | 6 +- content/news/2025-03-18.md | 2 +- content/news/2025-06-27.md | 4 +- content/news/2025-07-14.md | 16 +- content/news/2025-07-16.md | 2 +- content/news/2025-09-19.md | 8 +- content/news/2026-01-16.md | 12 +- content/news/2026-03-13.md | 2 +- content/news/2026-05-18.md | 2 +- content/news/2026-06-16.md | 2 +- content/news/2026-07-13.md | 2 +- content/news/2026-09-22.md | 14 +- content/news/_index.md | 10 +- content/news/v21.md | 6 +- content/news/v22.md | 12 +- content/news/v23.md | 2 +- content/news/v24.md | 2 +- content/news/v25.md | 12 +- content/news/v26.md | 14 +- content/news/v29.md | 16 +- content/news/v30.md | 14 +- content/news/v31.md | 16 +- content/news/v32.md | 4 +- content/news/v34.md | 2 +- content/overview.md | 186 +++++++++--------- content/programming-guides/_index.md | 2 +- content/programming-guides/addons.md | 6 +- .../programming-guides/deserialize-debug.md | 12 +- content/programming-guides/editions.md | 170 ++++++++-------- content/programming-guides/encoding.md | 48 ++--- content/programming-guides/enum.md | 6 +- content/programming-guides/field_presence.md | 30 ++- content/programming-guides/json.md | 18 +- content/programming-guides/proto2.md | 172 ++++++++-------- content/programming-guides/proto3.md | 162 ++++++++------- .../serialization-not-canonical.md | 6 +- content/programming-guides/style.md | 6 +- content/programming-guides/techniques.md | 52 +++-- content/reference/_index.md | 14 +- content/reference/cpp/_index.md | 2 +- content/reference/cpp/abseil.md | 6 +- content/reference/cpp/api-docs/_index.md | 8 +- .../cpp/api-docs/google.protobuf.arena.md | 4 +- .../cpp/api-docs/google.protobuf.common.md | 2 +- ...google.protobuf.compiler.code_generator.md | 6 +- ...rotobuf.compiler.command_line_interface.md | 2 +- .../google.protobuf.compiler.cpp_generator.md | 2 +- ...ogle.protobuf.compiler.csharp_generator.md | 2 +- .../google.protobuf.compiler.csharp_names.md | 2 +- .../google.protobuf.compiler.importer.md | 2 +- ...google.protobuf.compiler.java_generator.md | 2 +- .../google.protobuf.compiler.java_names.md | 2 +- ...le.protobuf.compiler.javanano_generator.md | 2 +- .../google.protobuf.compiler.js_generator.md | 6 +- ....protobuf.compiler.objectivec_generator.md | 4 +- ...le.protobuf.compiler.objectivec_helpers.md | 2 +- .../google.protobuf.compiler.parser.md | 2 +- .../google.protobuf.compiler.plugin.md | 2 +- .../google.protobuf.compiler.plugin.pb.md | 2 +- ...ogle.protobuf.compiler.python_generator.md | 4 +- ...google.protobuf.compiler.ruby_generator.md | 4 +- .../api-docs/google.protobuf.descriptor.md | 10 +- .../api-docs/google.protobuf.descriptor.pb.md | 4 +- .../google.protobuf.descriptor_database.md | 2 +- .../google.protobuf.dynamic_message.md | 2 +- .../google.protobuf.io.coded_stream.md | 6 +- .../google.protobuf.io.gzip_stream.md | 2 +- .../api-docs/google.protobuf.io.printer.md | 6 +- .../api-docs/google.protobuf.io.tokenizer.md | 2 +- .../google.protobuf.io.zero_copy_stream.md | 4 +- ...oogle.protobuf.io.zero_copy_stream_impl.md | 4 +- ....protobuf.io.zero_copy_stream_impl_lite.md | 4 +- .../cpp/api-docs/google.protobuf.map.md | 8 +- .../cpp/api-docs/google.protobuf.message.md | 6 +- .../api-docs/google.protobuf.message_lite.md | 34 ++-- .../google.protobuf.repeated_field.md | 4 +- .../cpp/api-docs/google.protobuf.service.md | 4 +- .../api-docs/google.protobuf.text_format.md | 10 +- .../google.protobuf.unknown_field_set.md | 4 +- .../google.protobuf.util.field_comparator.md | 10 +- .../google.protobuf.util.field_mask_util.md | 8 +- .../google.protobuf.util.json_util.md | 12 +- ...oogle.protobuf.util.message_differencer.md | 6 +- .../google.protobuf.util.time_util.md | 2 +- .../google.protobuf.util.type_resolver.md | 2 +- ...google.protobuf.util.type_resolver_util.md | 2 +- content/reference/cpp/arenas.md | 27 +-- content/reference/cpp/cpp-generated.md | 71 ++++--- content/reference/cpp/string-view.md | 4 +- content/reference/csharp/_index.md | 2 +- content/reference/csharp/csharp-generated.md | 52 ++--- content/reference/dart/_index.md | 2 +- content/reference/dart/dart-generated.md | 36 ++-- content/reference/go/_index.md | 2 +- content/reference/go/faq.md | 115 ++++++----- content/reference/go/go-generated-opaque.md | 40 ++-- content/reference/go/go-generated.md | 36 ++-- content/reference/go/opaque-faq.md | 16 +- .../reference/go/opaque-migration-manual.md | 10 +- content/reference/go/opaque-migration.md | 20 +- content/reference/java/_index.md | 2 +- content/reference/java/java-generated.md | 139 +++++++------ content/reference/kotlin/_index.md | 2 +- content/reference/kotlin/api-docs/_index.md | 2 +- .../-dsl-list/_index.md | 6 +- .../-dsl-map/_index.md | 6 +- .../-proto-dsl-marker/_index.md | 2 +- content/reference/kotlin/kotlin-generated.md | 22 +-- content/reference/objective-c/_index.md | 2 +- .../objective-c/objective-c-generated.md | 62 +++--- content/reference/other.md | 13 +- content/reference/php/_index.md | 2 +- content/reference/php/php-generated.md | 55 +++--- content/reference/protobuf/_index.md | 6 +- .../reference/protobuf/edition-2023-spec.md | 8 +- .../reference/protobuf/edition-2024-spec.md | 8 +- content/reference/protobuf/google.protobuf.md | 25 ++- content/reference/protobuf/mime-types.md | 6 +- content/reference/protobuf/proto2-spec.md | 8 +- content/reference/protobuf/proto3-spec.md | 10 +- content/reference/protobuf/textformat-spec.md | 8 +- content/reference/python/_index.md | 2 +- content/reference/python/python-comparison.md | 10 +- content/reference/python/python-generated.md | 108 +++++----- content/reference/ruby/_index.md | 2 +- content/reference/ruby/ruby-generated.md | 23 ++- content/reference/rust/_index.md | 2 +- .../reference/rust/rust-design-decisions.md | 16 +- content/reference/rust/rust-generated.md | 25 ++- content/support/_index.md | 8 +- content/support/debugging-playbook.md | 4 +- content/support/migration.md | 24 +-- 175 files changed, 1688 insertions(+), 1728 deletions(-) diff --git a/content/_index.md b/content/_index.md index 471fe8375..983478d15 100644 --- a/content/_index.md +++ b/content/_index.md @@ -1,25 +1,26 @@ +++ -title = "Protocol Buffers" +title = "Protobuf" weight = 5 toc_hide = "true" -description = "Protocol Buffers are language-neutral, platform-neutral extensible mechanisms for serializing structured data." +description = "Protobuf is a language-neutral, platform-neutral extensible mechanism for serializing structured data." type = "docs" no_list = "true" +++ -## What Are Protocol Buffers? +## What Is Protobuf? -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. +Protobuf ("Protocol Buffers") is 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, Rust, and Ruby. With proto3, you can also work with PHP. +Protobuf supports generated code in C++, C#, Dart, Go, +Java, Kotlin, Objective-C, Python, Rust, and Ruby. With proto3, +you can also work with PHP. ## Example Implementation @@ -67,7 +68,7 @@ email = john.email();
  • Download - and install the protocol buffer compiler. + and install the Protobuf compiler.
  • diff --git a/content/best-practices/1-1-1.md b/content/best-practices/1-1-1.md index 8fd3806d1..6b357fe2f 100644 --- a/content/best-practices/1-1-1.md +++ b/content/best-practices/1-1-1.md @@ -44,7 +44,7 @@ for when to diverge from the guideline. ## Symbol Visibility in Edition 2024 and Later {#2024-later} -Starting in `edition = "2024"`, Protocol Buffers introduces +Starting in `edition = "2024"`, Protobuf introduces [Symbol Visibility](/programming-guides/symbol_visibility) with `export` and `local` keywords and the `features.default_symbol_visibility` option. diff --git a/content/best-practices/dos-donts.md b/content/best-practices/dos-donts.md index a3905499a..5b3184b06 100644 --- a/content/best-practices/dos-donts.md +++ b/content/best-practices/dos-donts.md @@ -1,7 +1,7 @@ +++ title = "Proto Best Practices" weight = 90 -description = "Shares vetted best practices for authoring Protocol Buffers." +description = "Shares vetted best practices for authoring Protobuf schemas." type = "docs" aliases = "/programming-guides/dos-donts" +++ @@ -71,7 +71,7 @@ To safely remove the original name (if it's being used for interchange, which it Almost never change the type of a field; it'll mess up deserialization, same as re-using a tag number. The -[protobuf docs](/programming-guides/editions#updating) +[Protobuf docs](/programming-guides/editions#updating) outline cases where old binary encoded data may successfully parse under a different type (for example, going between `int32`, `uint32`, `int64` and `bool`). However, changing a field's type can be difficult to roll out safely @@ -191,9 +191,9 @@ when a perfectly suitable common type already exists! is a color in the RGBA color space. **Note:** While the "Well-Known Types" (such as `Duration` and `Timestamp`) are -included with the Protocol Buffers compiler, the "Common Types" (such as `Date` -and `Money`) are not. To use the Common Types, you may need to add a dependency -on the [googleapis repository](https://github.com/googleapis/googleapis). +included with the Protobuf compiler, the "Common Types" (such as `Date` and +`Money`) are not. To use the Common Types, you may need to add a dependency on +the [googleapis repository](https://github.com/googleapis/googleapis). @@ -279,7 +279,7 @@ For example: Text-based serialization formats like text format and JSON represent fields and enum values as strings. As a result, deserialization -of protocol buffers in these formats using old code will fail when a field or +of Protobuf messages in these formats using old code will fail when a field or enum value is renamed, or when a new field or enum value or extension is added. Use binary serialization when possible for data interchange, and use text format for human editing and debugging only. @@ -341,7 +341,7 @@ overrides are possible. ## Avoid Using Language Keywords for Field Names {#avoid-keywords} If the name of a message, field, enum, or enum value is a keyword in the -language that reads from/writes to that field, then protobuf may change the +language that reads from/writes to that field, then Protobuf may change the field name, and may have different ways to access them than normal fields. For example, see [this warning about Python](/reference/python/python-generated#keyword-conflicts). diff --git a/content/downloads.md b/content/downloads.md index 757d79504..699781baf 100644 --- a/content/downloads.md +++ b/content/downloads.md @@ -1,7 +1,7 @@ +++ title = "Downloads" weight = 1000 -description = "The downloads page for protocol buffers." +description = "The downloads page for Protobuf." type = "docs" +++ @@ -9,7 +9,7 @@ type = "docs" ### Latest Version -The latest release of Protocol Buffers can be found on the +The latest release of Protobuf can be found on the [release page](https://github.com/protocolbuffers/protobuf/releases/latest). ### Old Versions @@ -21,5 +21,5 @@ Older versions are available in our historical releases ### GitHub Repository -Protocol Buffers source code is hosted on +Protobuf source code is hosted on [GitHub](https://github.com/protocolbuffers/protobuf). diff --git a/content/editions/features.md b/content/editions/features.md index b7ed6e1c0..11d959d4d 100644 --- a/content/editions/features.md +++ b/content/editions/features.md @@ -1,7 +1,7 @@ +++ title = "Feature Settings for Editions" weight = 43 -description = "Protobuf Editions features and how they affect protobuf behavior." +description = "Protobuf Editions features and how they affect Protobuf behavior." type = "docs" +++ @@ -388,7 +388,7 @@ enum Foo { ### `features.field_presence` {#field_presence} This feature sets the behavior for tracking field presence, or the notion of -whether a protobuf field has a value. +whether a Protobuf field has a value. **Values available:** @@ -754,10 +754,10 @@ sections show these imports. **Languages:** Go -The `api_level` feature enables you to select which API version the Go protobuf +The `api_level` feature enables you to select which API version the Go Protobuf plugin should generate code for. The Opaque API is the latest version of the -Protocol Buffers implementation for the Go programming language. The previous -version is now called Open Struct API. See the +Protobuf implementation for the Go programming language. The previous version is +now called Open Struct API. See the [Go Protobuf: Releasing the Opaque API](https://go.dev/blog/protobuf-opaque) blog post for an introduction. diff --git a/content/editions/overview.md b/content/editions/overview.md index 3bd10c6e0..144d38c29 100644 --- a/content/editions/overview.md +++ b/content/editions/overview.md @@ -7,16 +7,16 @@ 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. -Editions enable the language to evolve incrementally over time. +for Protobuf. 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. Editions enable +the language to evolve incrementally over time. Instead of the hardcoded behaviors that older versions have had, editions represent a collection of [features](/editions/features) with a default value (behavior) per feature. Features are options on a file, message, field, enum, and so on, that specify the behavior of protoc, the code -generators, and protobuf runtimes. You can explicitly override a behavior at +generators, and Protobuf runtimes. You can explicitly override a behavior at those different levels (file, message, field, ...) when your needs don't match 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 @@ -40,7 +40,7 @@ it. For example: 3. A later edition, such as edition 2033, switches the default of `feature.amazing_new_feature` from `false` to `true`. This is the desired - behavior for all protos, and the reason that the protobuf team created the + behavior for all protos, and the reason that the Protobuf team created the feature. Using the Prototiller tool to migrate earlier versions of proto files to @@ -413,7 +413,7 @@ proto_library( ``` Option imports and `option_deps` are strongly recommended when importing -protobuf language features and other custom options to avoid generating +Protobuf language features and other custom options to avoid generating unnecessary code. This replaces `import weak`, which was removed in Edition 2024. diff --git a/content/getting-started/_index.md b/content/getting-started/_index.md index 7ca41d2fb..dc5b64865 100644 --- a/content/getting-started/_index.md +++ b/content/getting-started/_index.md @@ -3,12 +3,12 @@ +++ title = "Tutorials" weight = 200 -description = "Each tutorial in this section shows you how to implement a simple application using protocol buffers in your favourite language, introducing you to the language's protocol buffer API as well as showing you the basics of creating and using .proto files." +description = "Each tutorial in this section shows you how to implement a simple application using Protobuf in your favourite language, introducing you to the language's Protobuf API as well as showing you the basics of creating and using .proto files." type = "docs" +++ The complete sample code for each application is also provided. -The tutorials don't assume that you know anything about protocol buffers, but do -assume that you are comfortable writing code in your chosen language, including -using file I/O. +The tutorials don't assume that you know anything about Protobuf, but do assume +that you are comfortable writing code in your chosen language, including using +file I/O. diff --git a/content/getting-started/cpptutorial.md b/content/getting-started/cpptutorial.md index 403d4bf5c..60d1475e8 100644 --- a/content/getting-started/cpptutorial.md +++ b/content/getting-started/cpptutorial.md @@ -1,22 +1,22 @@ +++ -title = "Protocol Buffer Basics: C++" +title = "Protobuf Basics: C++" weight = 210 linkTitle = "C++" -description = "A basic C++ programmers introduction to working with protocol buffers." +description = "A basic C++ programmers introduction to working with Protobuf." type = "docs" +++ This tutorial provides a basic C++ programmers introduction to working with -protocol buffers. By walking through creating a simple example application, it -shows you how to +Protobuf. By walking through creating a simple example application, it shows you +how to - Define message formats in a `.proto` file. -- Use the protocol buffer compiler. -- Use the C++ protocol buffer API to write and read messages. +- Use the Protobuf compiler. +- Use the C++ Protobuf API to write and read messages. -This isn't a comprehensive guide to using protocol buffers in C++. For more -detailed reference information, see the -[Protocol Buffer Language Guide](/programming-guides/editions), +This isn't a comprehensive guide to using Protobuf in C++. For more detailed +reference information, see the +[Protobuf Language Guide](/programming-guides/editions), the [C++ API Reference](/reference/cpp/api-docs), the [C++ Generated Code Guide](/reference/cpp/cpp-generated), and the @@ -51,16 +51,16 @@ ways to solve this problem: Also, navigating an XML DOM tree is considerably more complicated than navigating simple fields in a class normally would be. -Instead of these options, you can use protocol buffers. Protocol buffers are the -flexible, efficient, automated solution to solve exactly this problem. With -protocol buffers, you write a `.proto` description of the data structure you -wish to store. From that, the protocol buffer compiler creates a class that -implements automatic encoding and parsing of the protocol buffer data with an -efficient binary format. The generated class provides getters and setters for -the fields that make up a protocol buffer and takes care of the details of -reading and writing the protocol buffer as a unit. Importantly, the protocol -buffer format supports the idea of extending the format over time in such a way -that the code can still read data encoded with the old format. +Instead of these options, you can use Protobuf. Protobuf is the flexible, +efficient, automated solution to solve exactly this problem. With Protobuf, you +write a `.proto` description of the data structure you wish to store. From that, +the Protobuf compiler creates a class that implements automatic encoding and +parsing of the Protobuf data with an efficient binary format. The generated +class provides getters and setters for the fields that make up a Protobuf +message and takes care of the details of reading and writing the message as a +unit. Importantly, the Protobuf format supports the idea of extending the format +over time in such a way that the code can still read data encoded with the old +format. ## Where to Find the Example Code {#example-code} @@ -148,25 +148,26 @@ Fields can be one of the following: zero). The order of the repeated values will be preserved. Think of repeated fields as dynamically sized arrays. -In older versions of protobuf, a `required` keyword existed, but it has been -found to be brittle and is not supported in modern protobufs (though editions -does have a feature you can use to enable it, for backward compatibility). +In older versions of Protobuf, a `required` keyword existed, but it has been +found to be brittle and is not supported in modern versions of Protobuf (though +editions does have a feature you can use to enable it, for backward +compatibility). You'll find a complete guide to writing `.proto` files -- including all the possible field types -- in the -[Protocol Buffer Language Guide](/programming-guides/editions). -Don't go looking for facilities similar to class inheritance, though -- protocol -buffers don't do that. +[Protobuf Language Guide](/programming-guides/editions). +Don't go looking for facilities similar to class inheritance, though -- Protobuf +doesn't do that. -## Compiling Your Protocol Buffers {#compiling-protocol-buffers} +## Compiling Your Protobuf Schema {#compiling-protocol-buffers} Now that you have a `.proto`, the next thing you need to do is generate the classes you'll need to read and write `AddressBook` (and hence `Person` and -`PhoneNumber`) messages. To do this, you need to run the protocol buffer -compiler `protoc` on your `.proto`: +`PhoneNumber`) messages. To do this, you need to run the Protobuf compiler +`protoc` on your `.proto`: 1. If you haven't installed the compiler, follow the instructions in - [Protocol Buffer Compiler Installation](/installation/). + [Protobuf Compiler Installation](/installation/). 2. Now run the compiler, specifying the source directory (where your application's source code lives -- the current directory is used if you @@ -186,7 +187,7 @@ This generates the following files in your specified destination directory: - `addressbook.pb.h`, the header which declares your generated classes. - `addressbook.pb.cc`, which contains the implementation of your classes. -## The Protocol Buffer API {#protobuf-api} +## The Protobuf API {#protobuf-api} Let's look at some of the generated code and see what classes and functions the compiler has created for you. If you look in `addressbook.pb.h`, you can see @@ -283,14 +284,13 @@ manipulate the entire message, including: - `void Clear();`: clears all the elements back to the empty state. These and the I/O methods described in the following section implement the -`Message` interface shared by all C++ protocol buffer classes. For more info, -see the +`Message` interface shared by all C++ Protobuf classes. For more info, see the [complete API documentation for `Message`](/reference/cpp/api-docs/google.protobuf.message#Message). ### Parsing and Serialization {#parsing-serialization} -Finally, each protocol buffer class has methods for writing and reading messages -of your chosen type using the protocol buffer +Finally, each Protobuf class has methods for writing and reading messages of +your chosen type using the Protobuf [binary format](/programming-guides/encoding). These include: @@ -309,12 +309,12 @@ See the [`Message` API reference](/reference/cpp/api-docs/google.protobuf.message#Message) for a complete list. -{{% alert title="Important" color="warning" %}} **Protocol Buffers and Object Oriented Design** -Protocol buffer classes are basically data holders (like structs in C) that -don't provide additional functionality; they don't make good first class -citizens in an object model. If you want to add richer behavior to a generated -class, the best way to do this is to wrap the generated protocol buffer class in -an application-specific class. Wrapping protocol buffers is also a good idea if +{{% alert title="Important" color="warning" %}} **Protobuf and Object Oriented Design** +Protobuf classes are basically data holders (like structs in C) that don't +provide additional functionality; they don't make good first class citizens in +an object model. If you want to add richer behavior to a generated class, the +best way to do this is to wrap the generated Protobuf class in an +application-specific class. Wrapping Protobuf messages is also a good idea if you don't have control over the design of the .proto file (if, say, you're reusing one from another project). In that case, you can use the wrapper class to craft an interface better suited to the unique environment of your @@ -323,14 +323,14 @@ application: hiding some data and methods, exposing convenience functions, etc. they are final. This prevents breaking internal mechanisms and is not good object-oriented practice anyway. - {{% /alert %}} +{{% /alert %}} ## Writing a Message {#writing-a-message} -Now let's try using your protocol buffer classes. The first thing you want your -address book application to be able to do is write personal details to your -address book file. To do this, you need to create and populate instances of your -protocol buffer classes and then write them to an output stream. +Now let's try using your Protobuf classes. The first thing you want your address +book application to be able to do is write personal details to your address book +file. To do this, you need to create and populate instances of your Protobuf +classes and then write them to an output stream. Here is a program that reads an `AddressBook` from a file, adds one new `Person` to it based on user input, and writes the new `AddressBook` back out to the file @@ -434,20 +434,20 @@ int main(int argc, char* argv[]) { ``` Notice the `GOOGLE_PROTOBUF_VERIFY_VERSION` macro. It is good practice -- though -not strictly necessary -- to execute this macro before using the C++ Protocol -Buffer library. It verifies that you have not accidentally linked against a -version of the library which is incompatible with the version of the headers you -compiled with. If a version mismatch is detected, the program will abort. Note -that every `.pb.cc` file automatically invokes this macro on startup. +not strictly necessary -- to execute this macro before using the C++ Protobuf +library. It verifies that you have not accidentally linked against a version of +the library which is incompatible with the version of the headers you compiled +with. If a version mismatch is detected, the program will abort. Note that every +`.pb.cc` file automatically invokes this macro on startup. Also notice the call to `ShutdownProtobufLibrary()` at the end of the program. -All this does is delete any global objects that were allocated by the Protocol -Buffer library. This is unnecessary for most programs, since the process is just -going to exit anyway and the OS will take care of reclaiming all of its memory. +All this does is delete any global objects that were allocated by the Protobuf +library. This is unnecessary for most programs, since the process is just going +to exit anyway and the OS will take care of reclaiming all of its memory. However, if you use a memory leak checker that requires that every last object be freed, or if you are writing a library which may be loaded and unloaded -multiple times by a single process, then you may want to force Protocol Buffers -to clean up everything. +multiple times by a single process, then you may want to force Protobuf to clean +up everything. ## Reading a Message {#reading-a-message} @@ -524,19 +524,19 @@ int main(int argc, char* argv[]) { } ``` -## Extending a Protocol Buffer {#extending-a-protobuf} +## Extending a Protobuf Message {#extending-a-protobuf} -Sooner or later after you release the code that uses your protocol buffer, you -will undoubtedly want to "improve" the protocol buffer's definition. If you want -your new buffers to be backwards-compatible, and your old buffers to be +Sooner or later after you release the code that uses your Protobuf message, you +will undoubtedly want to "improve" the message's definition. If you want your +new messages to be backwards-compatible, and your old messages to be forward-compatible -- and you almost certainly do want this -- then there are -some rules you need to follow. In the new version of the protocol buffer: +some rules you need to follow. In the new version of the message: * you *must not* change the field numbers of any existing fields. * you *may* delete singular or repeated fields. * you *may* add new singular or repeated fields but you must use fresh field - numbers (that is, field numbers that were never used in this protocol - buffer, not even by deleted fields). + numbers (that is, field numbers that were never used in this message, not + even by deleted fields). (There are [some exceptions](/programming-guides/editions#updating) @@ -552,16 +552,16 @@ before use. ## Optimization Tips {#optimization} -The C++ Protocol Buffers library is extremely heavily optimized. However, proper -usage can improve performance even more. Here are some tips for squeezing every -last drop of speed out of the library: +The C++ Protobuf library is extremely heavily optimized. However, proper usage +can improve performance even more. Here are some tips for squeezing every last +drop of speed out of the library: -- **Use Arenas for memory allocation.** When you create many protocol buffer - messages in a short-lived operation (like parsing a single request), the - system's memory allocator can become a bottleneck. Arenas are designed to - mitigate this. By using an arena, you can perform many allocations with low - overhead, and a single deallocation for all of them at once. This can - significantly improve performance in message-heavy applications. +- **Use Arenas for memory allocation.** When you create many Protobuf messages + in a short-lived operation (like parsing a single request), the system's + memory allocator can become a bottleneck. Arenas are designed to mitigate + this. By using an arena, you can perform many allocations with low overhead, + and a single deallocation for all of them at once. This can significantly + improve performance in message-heavy applications. To use arenas, you allocate messages on a `google::protobuf::Arena` object: @@ -610,9 +610,9 @@ last drop of speed out of the library: ## Advanced Usage {#advanced-usage} -Protocol buffers have uses that go beyond simple accessors and serialization. Be -sure to explore the [C++ API reference](/reference/cpp) -to see what else you can do with them. +Protobuf has uses that go beyond simple accessors and serialization. Be sure to +explore the [C++ API reference](/reference/cpp) to see +what else you can do with it. One key feature provided by protocol message classes is *reflection*. You can iterate over the fields of a message and manipulate their values without writing @@ -622,8 +622,7 @@ as XML or JSON. A more advanced use of reflection might be to find differences between two messages of the same type, or to develop a sort of "regular expressions for protocol messages" in which you can write expressions that match certain message contents. If you use your imagination, it's possible to apply -Protocol Buffers to a much wider range of problems than you might initially -expect! +Protobuf to a much wider range of problems than you might initially expect! Reflection is provided by the [`Message::Reflection` interface](/reference/cpp/api-docs/google.protobuf.message#Reflection). diff --git a/content/getting-started/csharptutorial.md b/content/getting-started/csharptutorial.md index 5b0be8257..2c2330ade 100644 --- a/content/getting-started/csharptutorial.md +++ b/content/getting-started/csharptutorial.md @@ -1,24 +1,23 @@ +++ -title = "Protocol Buffer Basics: C#" +title = "Protobuf Basics: C#" weight = 220 linkTitle = "C#" -description = "A basic C# programmers introduction to working with protocol buffers." +description = "A basic C# programmers introduction to working with Protobuf." type = "docs" +++ This tutorial provides a basic C# programmer's introduction to working with -protocol buffers, using the -[proto3](/programming-guides/proto3) version of the -protocol buffers language. By walking through creating a simple example +Protobuf, using the [proto3](/programming-guides/proto3) +version of the Protobuf language. By walking through creating a simple example application, it shows you how to - Define message formats in a `.proto` file. -- Use the protocol buffer compiler. -- Use the C# protocol buffer API to write and read messages. +- Use the Protobuf compiler. +- Use the C# Protobuf API to write and read messages. -This isn't a comprehensive guide to using protocol buffers in C#. For more -detailed reference information, see the -[Protocol Buffer Language Guide](/programming-guides/proto3), +This isn't a comprehensive guide to using Protobuf in C#. For more detailed +reference information, see the +[Protobuf Language Guide](/programming-guides/proto3), the [C# API Reference](/reference/csharp/api-docs), the [C# Generated Code Guide](/reference/csharp/csharp-generated), and the @@ -53,21 +52,20 @@ ways to solve this problem: Also, navigating an XML DOM tree is considerably more complicated than navigating simple fields in a class normally would be. -Protocol buffers are the flexible, efficient, automated solution to solve -exactly this problem. With protocol buffers, you write a `.proto` description of -the data structure you wish to store. From that, the protocol buffer compiler -creates a class that implements automatic encoding and parsing of the protocol -buffer data with an efficient binary format. The generated class provides -getters and setters for the fields that make up a protocol buffer and takes care -of the details of reading and writing the protocol buffer as a unit. -Importantly, the protocol buffer format supports the idea of extending the -format over time in such a way that the code can still read data encoded with -the old format. +Protobuf is the flexible, efficient, automated solution to solve exactly this +problem. With Protobuf, you write a `.proto` description of the data structure +you wish to store. From that, the Protobuf compiler creates a class that +implements automatic encoding and parsing of the Protobuf data with an efficient +binary format. The generated class provides getters and setters for the fields +that make up a Protobuf message and takes care of the details of reading and +writing the message as a unit. Importantly, the Protobuf format supports the +idea of extending the format over time in such a way that the code can still +read data encoded with the old format. ## Where to Find the Example Code {#example-code} Our example is a command-line application for managing an address book data -file, encoded using protocol buffers. The command `AddressBook` (see: +file, encoded using Protobuf. The command `AddressBook` (see: [Program.cs](//github.com/protocolbuffers/protobuf/blob/master/csharp/src/AddressBook/Program.cs)) can add a new entry to the data file or parse the data file and print the data to the console. @@ -168,20 +166,20 @@ returns that field's default value. If a field is `repeated`, the field may be repeated any number of times (including zero). The order of the repeated values will be preserved in the -protocol buffer. Think of repeated fields as dynamically sized arrays. +Protobuf message. Think of repeated fields as dynamically sized arrays. You'll find a complete guide to writing `.proto` files -- including all the possible field types -- in the -[Protocol Buffer Language Guide](/programming-guides/proto3). -Don't go looking for facilities similar to class inheritance, though -- protocol -buffers don't do that. +[Protobuf Language Guide](/programming-guides/proto3). +Don't go looking for facilities similar to class inheritance, though -- Protobuf +doesn't do that. -## Compiling Your Protocol Buffers {#compiling-protocol-buffers} +## Compiling Your Protobuf Schema {#compiling-protocol-buffers} Now that you have a `.proto`, the next thing you need to do is generate the classes you'll need to read and write `AddressBook` (and hence `Person` and -`PhoneNumber`) messages. To do this, you need to run the protocol buffer -compiler `protoc` on your `.proto`: +`PhoneNumber`) messages. To do this, you need to run the Protobuf compiler +`protoc` on your `.proto`: 1. If you haven't installed the compiler, [download the package](/downloads) and follow the @@ -208,8 +206,8 @@ compile this code, you'll need a project with a reference to the Generating `Addressbook.cs` gives you five useful types: -- A static `Addressbook` class that contains metadata about the protocol - buffer messages. +- A static `Addressbook` class that contains metadata about the Protobuf + messages. - An `AddressBook` class with a read-only `People` property. - A `Person` class with properties for `Name`, `Id`, `Email` and `Phones`. - A `PhoneNumber` class, nested in a static `Person.Types` class. @@ -250,15 +248,14 @@ Phones = { new PhoneNumber { Number = "555-4321", Type = PhoneType.HOME } } ## Parsing and Serialization {#parsing-serialization} -The whole purpose of using protocol buffers is to serialize your data so that it -can be parsed elsewhere. Every generated class has a -`WriteTo(CodedOutputStream)` method, where `CodedOutputStream` is a class in the -protocol buffer runtime library. However, usually you'll use one of the -extension methods to write to a regular `System.IO.Stream` or convert the -message to a byte array or `ByteString`. These extension messages are in the -`Google.Protobuf.MessageExtensions` class, so when you want to serialize you'll -usually want a `using` directive for the `Google.Protobuf` namespace. For -example: +The whole purpose of using Protobuf is to serialize your data so that it can be +parsed elsewhere. Every generated class has a `WriteTo(CodedOutputStream)` +method, where `CodedOutputStream` is a class in the Protobuf runtime library. +However, usually you'll use one of the extension methods to write to a regular +`System.IO.Stream` or convert the message to a byte array or `ByteString`. These +extension methods are in the `Google.Protobuf.MessageExtensions` class, so when +you want to serialize you'll usually want a `using` directive for the +`Google.Protobuf` namespace. For example: ```csharp using Google.Protobuf; @@ -285,21 +282,20 @@ using (var input = File.OpenRead("john.dat")) A full example program to maintain an addressbook (adding new entries and listing existing ones) using these messages is available -[in the Github repository](https://github.com/protocolbuffers/protobuf/tree/master/csharp/src/AddressBook). +[in the GitHub repository](https://github.com/protocolbuffers/protobuf/tree/master/csharp/src/AddressBook). -## Extending a Protocol Buffer {#extending-a-protobuf} +## Extending a Protobuf Message {#extending-a-protobuf} -Sooner or later after you release the code that uses your protocol buffer, you -will undoubtedly want to "improve" the protocol buffer's definition. If you want -your new buffers to be backwards-compatible, and your old buffers to be +Sooner or later after you release the code that uses your Protobuf message, you +will undoubtedly want to "improve" the message's definition. If you want your +new messages to be backwards-compatible, and your old messages to be forward-compatible -- and you almost certainly do want this -- then there are -some rules you need to follow. In the new version of the protocol buffer: +some rules you need to follow. In the new version of the message: - you *must not* change the tag numbers of any existing fields. - you *may* delete fields. - you *may* add new fields but you must use fresh tag numbers (i.e. tag - numbers that were never used in this protocol buffer, not even by deleted - fields). + numbers that were never used in this message, not even by deleted fields). (There are [some exceptions](/programming-guides/proto3#updating) to diff --git a/content/getting-started/darttutorial.md b/content/getting-started/darttutorial.md index 2d66ea7ee..21bea9ce3 100644 --- a/content/getting-started/darttutorial.md +++ b/content/getting-started/darttutorial.md @@ -1,24 +1,23 @@ +++ -title = "Protocol Buffer Basics: Dart" +title = "Protobuf Basics: Dart" weight = 230 linkTitle = "Dart" -description = "A basic Dart programmers introduction to working with protocol buffers." +description = "A basic Dart programmers introduction to working with Protobuf." type = "docs" +++ This tutorial provides a basic Dart programmer's introduction to working with -protocol buffers, using the -[proto3](/programming-guides/proto3) version of the -protocol buffers language. By walking through creating a simple example +Protobuf, using the [proto3](/programming-guides/proto3) +version of the Protobuf language. By walking through creating a simple example application, it shows you how to - Define message formats in a `.proto` file. -- Use the protocol buffer compiler. -- Use the Dart protocol buffer API to write and read messages. +- Use the Protobuf compiler. +- Use the Dart Protobuf API to write and read messages. -This isn't a comprehensive guide to using protocol buffers in Dart . For more -detailed reference information, see the -[Protocol Buffer Language Guide](/programming-guides/proto3), +This isn't a comprehensive guide to using Protobuf in Dart. For more detailed +reference information, see the +[Protobuf Language Guide](/programming-guides/proto3), the [Dart Language Tour,](https://www.dartlang.org/guides/language/language-tour) the [Dart API Reference](https://pub.dartlang.org/documentation/protobuf), the @@ -49,23 +48,22 @@ ways to solve this problem: Also, navigating an XML DOM tree is considerably more complicated than navigating simple fields in a class normally would be. -Protocol buffers are the flexible, efficient, automated solution to solve -exactly this problem. With protocol buffers, you write a `.proto` description of -the data structure you wish to store. From that, the protocol buffer compiler -creates a class that implements automatic encoding and parsing of the protocol -buffer data with an efficient binary format. The generated class provides -getters and setters for the fields that make up a protocol buffer and takes care -of the details of reading and writing the protocol buffer as a unit. -Importantly, the protocol buffer format supports the idea of extending the -format over time in such a way that the code can still read data encoded with -the old format. +Protobuf is the flexible, efficient, automated solution to solve exactly this +problem. With Protobuf, you write a `.proto` description of the data structure +you wish to store. From that, the Protobuf compiler creates a class that +implements automatic encoding and parsing of the Protobuf data with an efficient +binary format. The generated class provides getters and setters for the fields +that make up a Protobuf message and takes care of the details of reading and +writing the message as a unit. Importantly, the Protobuf format supports the +idea of extending the format over time in such a way that the code can still +read data encoded with the old format. ## Where to Find the Example Code {#example-code} Our example is a set of command-line applications for managing an address book -data file, encoded using protocol buffers. The command `dart add_person.dart` -adds a new entry to the data file. The command `dart list_people.dart` parses -the data file and prints the data to the console. +data file, encoded using Protobuf. The command `dart add_person.dart` adds a new +entry to the data file. The command `dart list_people.dart` parses the data file +and prints the data to the console. You can find the complete example in the [examples directory](https://github.com/protocolbuffers/protobuf/tree/master/examples) @@ -151,29 +149,29 @@ returns that field's default value. If a field is `repeated`, the field may be repeated any number of times (including zero). The order of the repeated values will be preserved in the -protocol buffer. Think of repeated fields as dynamically sized arrays. +Protobuf message. Think of repeated fields as dynamically sized arrays. You'll find a complete guide to writing `.proto` files -- including all the possible field types -- in the -[Protocol Buffer Language Guide](/programming-guides/proto3). -Don't go looking for facilities similar to class inheritance, though -- protocol -buffers don't do that. +[Protobuf Language Guide](/programming-guides/proto3). +Don't go looking for facilities similar to class inheritance, though -- Protobuf +doesn't do that. -## Compiling Your Protocol Buffers {#compiling-protocol-buffers} +## Compiling Your Protobuf Schema {#compiling-protocol-buffers} Now that you have a `.proto`, the next thing you need to do is generate the classes you'll need to read and write `AddressBook` (and hence `Person` and -`PhoneNumber`) messages. To do this, you need to run the protocol buffer -compiler `protoc` on your `.proto`: +`PhoneNumber`) messages. To do this, you need to run the Protobuf compiler +`protoc` on your `.proto`: 1. If you haven't installed the compiler, [download the package](/downloads) and follow the instructions in the README. -2. Install the Dart Protocol Buffer plugin as described in +2. Install the Dart Protobuf plugin as described in [its README](https://github.com/google/protobuf.dart/tree/master/protoc_plugin#how-to-build). - The executable `bin/protoc-gen-dart` must be in your `PATH` for the protocol - buffer `protoc` to find it. + The executable `bin/protoc-gen-dart` must be in your `PATH` for the Protobuf + compiler `protoc` to find it. 3. Now run the compiler, specifying the source directory (where your application's source code lives -- the current directory is used if you @@ -190,7 +188,7 @@ compiler `protoc` on your `.proto`: This generates `addressbook.pb.dart` in your specified destination directory. -## The Protocol Buffer API {#protobuf-api} +## The Protobuf API {#protobuf-api} Generating `addressbook.pb.dart` gives you the following useful types: @@ -206,10 +204,10 @@ You can read more about the details of exactly what's generated in the ## Writing a Message {#writing-a-message} -Now let's try using your protocol buffer classes. The first thing you want your -address book application to be able to do is write personal details to your -address book file. To do this, you need to create and populate instances of your -protocol buffer classes and then write them to an output stream. +Now let's try using your Protobuf classes. The first thing you want your address +book application to be able to do is write personal details to your address book +file. To do this, you need to create and populate instances of your Protobuf +classes and then write them to an output stream. Here is a program which reads an `AddressBook` from a file, adds one new `Person` to it based on user input, and writes the new `AddressBook` back out to @@ -345,19 +343,18 @@ main(List arguments) { } ``` -## Extending a Protocol Buffer {#extending-a-protobuf} +## Extending a Protobuf Message {#extending-a-protobuf} -Sooner or later after you release the code that uses your protocol buffer, you -will undoubtedly want to "improve" the protocol buffer's definition. If you want -your new buffers to be backwards-compatible, and your old buffers to be +Sooner or later after you release the code that uses your Protobuf message, you +will undoubtedly want to "improve" the message's definition. If you want your +new messages to be backwards-compatible, and your old messages to be forward-compatible -- and you almost certainly do want this -- then there are -some rules you need to follow. In the new version of the protocol buffer: +some rules you need to follow. In the new version of the message: - you *must not* change the tag numbers of any existing fields. - you *may* delete fields. - you *may* add new fields but you must use fresh tag numbers (i.e. tag - numbers that were never used in this protocol buffer, not even by deleted - fields). + numbers that were never used in this message, not even by deleted fields). (There are [some exceptions](/programming-guides/proto3#updating) to diff --git a/content/getting-started/gotutorial.md b/content/getting-started/gotutorial.md index f295167d4..ff1823744 100644 --- a/content/getting-started/gotutorial.md +++ b/content/getting-started/gotutorial.md @@ -1,24 +1,23 @@ +++ -title = "Protocol Buffer Basics: Go" +title = "Protobuf Basics: Go" weight = 240 linkTitle = "Go" -description = "A basic Go programmers introduction to working with protocol buffers." +description = "A basic Go programmers introduction to working with Protobuf." type = "docs" +++ This tutorial provides a basic Go programmer's introduction to working with -protocol buffers, using the -[proto3](/programming-guides/proto3) version of the -protocol buffers language. By walking through creating a simple example +Protobuf, using the [proto3](/programming-guides/proto3) +version of the Protobuf language. By walking through creating a simple example application, it shows you how to - Define message formats in a `.proto` file. -- Use the protocol buffer compiler. -- Use the Go protocol buffer API to write and read messages. +- Use the Protobuf compiler. +- Use the Go Protobuf API to write and read messages. -This isn't a comprehensive guide to using protocol buffers in Go. For more -detailed reference information, see the -[Protocol Buffer Language Guide](/programming-guides/proto3), +This isn't a comprehensive guide to using Protobuf in Go. For more detailed +reference information, see the +[Protobuf Language Guide](/programming-guides/proto3), the [Go API Reference](https://pkg.go.dev/google.golang.org/protobuf/proto), the [Go Generated Code Guide](/reference/go/go-generated), and the @@ -51,23 +50,22 @@ ways to solve this problem: Also, navigating an XML DOM tree is considerably more complicated than navigating simple fields in a class normally would be. -Protocol buffers are the flexible, efficient, automated solution to solve -exactly this problem. With protocol buffers, you write a `.proto` description of -the data structure you wish to store. From that, the protocol buffer compiler -creates a class that implements automatic encoding and parsing of the protocol -buffer data with an efficient binary format. The generated class provides -getters and setters for the fields that make up a protocol buffer and takes care -of the details of reading and writing the protocol buffer as a unit. -Importantly, the protocol buffer format supports the idea of extending the -format over time in such a way that the code can still read data encoded with -the old format. +Protobuf is the flexible, efficient, automated solution to solve exactly this +problem. With Protobuf, you write a `.proto` description of the data structure +you wish to store. From that, the Protobuf compiler creates a class that +implements automatic encoding and parsing of the Protobuf data with an efficient +binary format. The generated class provides getters and setters for the fields +that make up a Protobuf message and takes care of the details of reading and +writing the message as a unit. Importantly, the Protobuf format supports the +idea of extending the format over time in such a way that the code can still +read data encoded with the old format. ## Where to Find the Example Code {#example-code} Our example is a set of command-line applications for managing an address book -data file, encoded using protocol buffers. The command `add_person_go` adds a -new entry to the data file. The command `list_people_go` parses the data file -and prints the data to the console. +data file, encoded using Protobuf. The command `add_person_go` adds a new entry +to the data file. The command `list_people_go` parses the data file and prints +the data to the console. You can find the complete example in the [examples directory](https://github.com/protocolbuffers/protobuf/tree/master/examples) @@ -162,26 +160,26 @@ returns that field's default value. If a field is `repeated`, the field may be repeated any number of times (including zero). The order of the repeated values will be preserved in the -protocol buffer. Think of repeated fields as dynamically sized arrays. +Protobuf message. Think of repeated fields as dynamically sized arrays. You'll find a complete guide to writing `.proto` files -- including all the possible field types -- in the -[Protocol Buffer Language Guide](/programming-guides/proto3). -Don't go looking for facilities similar to class inheritance, though -- protocol -buffers don't do that. +[Protobuf Language Guide](/programming-guides/proto3). +Don't go looking for facilities similar to class inheritance, though -- Protobuf +doesn't do that. -## Compiling Your Protocol Buffers {#compiling-protocol-buffers} +## Compiling Your Protobuf Schema {#compiling-protocol-buffers} Now that you have a `.proto`, the next thing you need to do is generate the classes you'll need to read and write `AddressBook` (and hence `Person` and -`PhoneNumber`) messages. To do this, you need to run the protocol buffer -compiler `protoc` on your `.proto`: +`PhoneNumber`) messages. To do this, you need to run the Protobuf compiler +`protoc` on your `.proto`: 1. If you haven't installed the compiler, [download the package](/downloads) and follow the instructions in the README. -2. Run the following command to install the Go protocol buffers plugin: +2. Run the following command to install the Go Protobuf plugin: ```shell go install google.golang.org/protobuf/cmd/protoc-gen-go@latest @@ -208,7 +206,7 @@ This generates `github.com/protocolbuffers/protobuf/examples/go/tutorialpb/addressbook.pb.go` in your specified destination directory. -## The Protocol Buffer API {#protobuf-api} +## The Protobuf API {#protobuf-api} Generating `addressbook.pb.go` gives you the following useful types: @@ -239,13 +237,13 @@ p := pb.Person{ ## Writing a Message {#writing-a-message} -The whole purpose of using protocol buffers is to serialize your data so that it -can be parsed elsewhere. In Go, you use the `proto` library's +The whole purpose of using Protobuf is to serialize your data so that it can be +parsed elsewhere. In Go, you use the `proto` library's [Marshal](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Marshal) -function to serialize your protocol buffer data. A pointer to a protocol buffer -message's `struct` implements the `proto.Message` interface. Calling -`proto.Marshal` returns the protocol buffer, encoded in its wire format. For -example, we use this function in the +function to serialize your Protobuf data. A pointer to a Protobuf message's +`struct` implements the `proto.Message` interface. Calling `proto.Marshal` +returns the Protobuf message, encoded in its wire format. For example, we use +this function in the [`add_person` command](https://github.com/protocolbuffers/protobuf/blob/master/examples/go/cmd/add_person/add_person.go): ```go @@ -266,7 +264,7 @@ if err := ioutil.WriteFile(fname, out, 0644); err != nil { To parse an encoded message, you use the `proto` library's [Unmarshal](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Unmarshal) -function. Calling this parses the data in `in` as a protocol buffer and places +function. Calling this parses the data in `in` as a Protobuf message and places the result in `book`. So to parse the file in the [`list_people` command](https://github.com/protocolbuffers/protobuf/blob/master/examples/go/cmd/list_people/list_people.go), we use: @@ -283,19 +281,18 @@ if err := proto.Unmarshal(in, book); err != nil { } ``` -## Extending a Protocol Buffer {#extending-a-protobuf} +## Extending a Protobuf Message {#extending-a-protobuf} -Sooner or later after you release the code that uses your protocol buffer, you -will undoubtedly want to "improve" the protocol buffer's definition. If you want -your new buffers to be backwards-compatible, and your old buffers to be +Sooner or later after you release the code that uses your Protobuf message, you +will undoubtedly want to "improve" the message's definition. If you want your +new messages to be backwards-compatible, and your old messages to be forward-compatible -- and you almost certainly do want this -- then there are -some rules you need to follow. In the new version of the protocol buffer: +some rules you need to follow. In the new version of the message: - you *must not* change the tag numbers of any existing fields. - you *may* delete fields. - you *may* add new fields but you must use fresh tag numbers (i.e. tag - numbers that were never used in this protocol buffer, not even by deleted - fields). + numbers that were never used in this message, not even by deleted fields). (There are [some exceptions](/programming-guides/proto3#updating) to diff --git a/content/getting-started/javatutorial.md b/content/getting-started/javatutorial.md index a97aab55c..83daea2e3 100644 --- a/content/getting-started/javatutorial.md +++ b/content/getting-started/javatutorial.md @@ -1,24 +1,24 @@ +++ -title = "Protocol Buffer Basics: Java" +title = "Protobuf Basics: Java" weight = 250 linkTitle = "Java" -description = "A basic Java programmers introduction to working with protocol buffers." +description = "A basic Java programmers introduction to working with Protobuf." type = "docs" +++ This tutorial provides a basic Java programmer's introduction to working with -protocol buffers. By walking through creating a simple example application, it -shows you how to +Protobuf. By walking through creating a simple example application, it shows you +how to - Define message formats in a `.proto` file. -- Use the protocol buffer compiler. -- Use the Java protocol buffer API to write and read messages. +- Use the Protobuf compiler. +- Use the Java Protobuf API to write and read messages. -This isn't a comprehensive guide to using protocol buffers in Java. For more -detailed reference information, see the -[Protocol Buffer Language Guide (proto2)](/programming-guides/proto2), +This isn't a comprehensive guide to using Protobuf in Java. For more detailed +reference information, see the +[Protobuf Language Guide (proto2)](/programming-guides/proto2), the -[Protocol Buffer Language Guide (proto3)](/programming-guides/proto3), +[Protobuf Language Guide (proto3)](/programming-guides/proto3), the [Java API Reference](/reference/java/api-docs/overview-summary.html), the @@ -53,16 +53,16 @@ ways to solve this problem: Also, navigating an XML DOM tree is considerably more complicated than navigating simple fields in a class normally would be. -Instead of these options, you can use protocol buffers. Protocol buffers are the -flexible, efficient, automated solution to solve exactly this problem. With -protocol buffers, you write a `.proto` description of the data structure you -wish to store. From that, the protocol buffer compiler creates a class that -implements automatic encoding and parsing of the protocol buffer data with an -efficient binary format. The generated class provides getters and setters for -the fields that make up a protocol buffer and takes care of the details of -reading and writing the protocol buffer as a unit. Importantly, the protocol -buffer format supports the idea of extending the format over time in such a way -that the code can still read data encoded with the old format. +Instead of these options, you can use Protobuf. Protobuf is the flexible, +efficient, automated solution to solve exactly this problem. With Protobuf, you +write a `.proto` description of the data structure you wish to store. From that, +the Protobuf compiler creates a class that implements automatic encoding and +parsing of the Protobuf data with an efficient binary format. The generated +class provides getters and setters for the fields that make up a Protobuf +message and takes care of the details of reading and writing the message as a +unit. Importantly, the Protobuf format supports the idea of extending the format +over time in such a way that the code can still read data encoded with the old +format. ## Where to Find the Example Code {#example-code} @@ -118,8 +118,8 @@ The `.proto` file starts with a package declaration, which helps to prevent naming conflicts between different projects. In Java, the package name is used as the Java package unless you have explicitly specified a `java_package`, as we have here. Even if you do provide a `java_package`, you should still define a -normal `package` as well to avoid name collisions in the Protocol Buffers name -space as well as in non-Java languages. +normal `package` as well to avoid name collisions in the Protobuf name space as +well as in non-Java languages. After the package declaration, you can see three options that are Java-specific: `java_multiple_files`, `java_package`, and `java_outer_classname`. @@ -168,7 +168,7 @@ Each field must be annotated with one of the following modifiers: optional (or required) field which has not been explicitly set always returns that field's default value. - `repeated`: the field may be repeated any number of times (including zero). - The order of the repeated values will be preserved in the protocol buffer. + The order of the repeated values will be preserved in the Protobuf message. Think of repeated fields as dynamically sized arrays. - `required`: a value for the field must be provided, otherwise the message will be considered "uninitialized". Trying to build an uninitialized message @@ -189,16 +189,16 @@ most messages defined in proto2 syntax use `optional` and `repeated` only. You'll find a complete guide to writing `.proto` files -- including all the possible field types -- in the -[Protocol Buffer Language Guide](/programming-guides/proto2). -Don't go looking for facilities similar to class inheritance, though -- protocol -buffers don't do that. +[Protobuf Language Guide](/programming-guides/proto2). +Don't go looking for facilities similar to class inheritance, though -- Protobuf +doesn't do that. -## Compiling Your Protocol Buffers {#compiling-protocol-buffers} +## Compiling Your Protobuf Schema {#compiling-protocol-buffers} Now that you have a `.proto`, the next thing you need to do is generate the classes you'll need to read and write `AddressBook` (and hence `Person` and -`PhoneNumber`) messages. To do this, you need to run the protocol buffer -compiler `protoc` on your `.proto`: +`PhoneNumber`) messages. To do this, you need to run the Protobuf compiler +`protoc` on your `.proto`: 1. If you haven't installed the compiler, [download the package](/downloads) and follow the @@ -220,7 +220,7 @@ compiler `protoc` on your `.proto`: This generates a `com/example/tutorial/protos/` subdirectory in your specified destination directory, containing a few generated `.java` files. -## The Protocol Buffer API {#protobuf-api} +## The Protobuf API {#protobuf-api} Let's look at some of the generated code and see what classes and methods the compiler has created for you. If you look in `com/example/tutorial/protos/`, you @@ -297,8 +297,8 @@ the list. Notice how these accessor methods use camel-case naming, even though the `.proto` file uses lowercase-with-underscores. This transformation is done -automatically by the protocol buffer compiler so that the generated classes -match standard Java style conventions. You should always use +automatically by the Protobuf compiler so that the generated classes match +standard Java style conventions. You should always use lowercase-with-underscores for field names in your `.proto` files; this ensures good naming practice in all the generated languages. See the [style guide](/programming-guides/style) for more on good @@ -328,11 +328,11 @@ class within `Person`. ### Builders vs. Messages {#builders-messages} -The message classes generated by the protocol buffer compiler are all -*immutable*. Once a message object is constructed, it cannot be modified, just -like a Java `String`. To construct a message, you must first construct a -builder, set any fields you want to set to your chosen values, then call the -builder's `build()` method. +The message classes generated by the Protobuf compiler are all *immutable*. Once +a message object is constructed, it cannot be modified, just like a Java +`String`. To construct a message, you must first construct a builder, set any +fields you want to set to your chosen values, then call the builder's `build()` +method. You may have noticed that each method of the builder which modifies the message returns another builder. The returned object is actually the same builder on @@ -374,8 +374,8 @@ all Java messages and builders. For more information, see the ### Parsing and Serialization {#parsing-serialization} -Finally, each protocol buffer class has methods for writing and reading messages -of your chosen type using the protocol buffer +Finally, each Protobuf class has methods for writing and reading messages of +your chosen type using the Protobuf [binary format](/programming-guides/encoding). These include: @@ -393,12 +393,12 @@ Again, see the [`Message` API reference](/reference/java/api-docs/com/google/protobuf/Message.html) for a complete list. -{{% alert title="Important" color="warning" %}} **Protocol Buffers and Object Oriented Design** -Protocol buffer classes are basically data holders (like structs in C) that -don't provide additional functionality; they don't make good first class -citizens in an object model. If you want to add richer behavior to a generated -class, the best way to do this is to wrap the generated protocol buffer class in -an application-specific class. Wrapping protocol buffers is also a good idea if +{{% alert title="Important" color="warning" %}} **Protobuf and Object Oriented Design** +Protobuf classes are basically data holders (like structs in C) that don't +provide additional functionality; they don't make good first class citizens in +an object model. If you want to add richer behavior to a generated class, the +best way to do this is to wrap the generated Protobuf class in an +application-specific class. Wrapping Protobuf messages is also a good idea if you don't have control over the design of the `.proto` file (if, say, you're reusing one from another project). In that case, you can use the wrapper class to craft an interface better suited to the unique environment of your @@ -409,10 +409,10 @@ practice anyway. {{% /alert %}} ## Writing a Message {#writing-a-message} -Now let's try using your protocol buffer classes. The first thing you want your -address book application to be able to do is write personal details to your -address book file. To do this, you need to create and populate instances of your -protocol buffer classes and then write them to an output stream. +Now let's try using your Protobuf classes. The first thing you want your address +book application to be able to do is write personal details to your address book +file. To do this, you need to create and populate instances of your Protobuf +classes and then write them to an output stream. Here is a program which reads an `AddressBook` from a file, adds one new `Person` to it based on user input, and writes the new `AddressBook` back out to @@ -564,20 +564,20 @@ class ListPeople { } ``` -## Extending a Protocol Buffer {#extending-a-protobuf} +## Extending a Protobuf Message {#extending-a-protobuf} -Sooner or later after you release the code that uses your protocol buffer, you -will undoubtedly want to "improve" the protocol buffer's definition. If you want -your new buffers to be backwards-compatible, and your old buffers to be +Sooner or later after you release the code that uses your Protobuf message, you +will undoubtedly want to "improve" the message's definition. If you want your +new messages to be backwards-compatible, and your old messages to be forward-compatible -- and you almost certainly do want this -- then there are -some rules you need to follow. In the new version of the protocol buffer: +some rules you need to follow. In the new version of the message: - you *must not* change the tag numbers of any existing fields. - you *must not* add or delete any required fields. - you *may* delete optional or repeated fields. - you *may* add new optional or repeated fields but you must use fresh tag - numbers (that is, tag numbers that were never used in this protocol buffer, - not even by deleted fields). + numbers (that is, tag numbers that were never used in this message, not even + by deleted fields). (There are [some exceptions](/programming-guides/proto2#updating) to @@ -599,10 +599,10 @@ or never set at all (by old code) since there is no `has_` flag for it. ## Advanced Usage {#advanced-usage} -Protocol buffers have uses that go beyond simple accessors and serialization. Be -sure to explore the +Protobuf has uses that go beyond simple accessors and serialization. Be sure to +explore the [Java API reference](/reference/java/api-docs/index-all.html) -to see what else you can do with them. +to see what else you can do with it. One key feature provided by protocol message classes is *reflection*. You can iterate over the fields of a message and manipulate their values without writing @@ -612,8 +612,7 @@ as XML or JSON. A more advanced use of reflection might be to find differences between two messages of the same type, or to develop a sort of "regular expressions for protocol messages" in which you can write expressions that match certain message contents. If you use your imagination, it's possible to apply -Protocol Buffers to a much wider range of problems than you might initially -expect! +Protobuf to a much wider range of problems than you might initially expect! Reflection is provided as part of the [`Message`](/reference/java/api-docs/com/google/protobuf/Message.html) diff --git a/content/getting-started/kotlintutorial.md b/content/getting-started/kotlintutorial.md index d2b67fcc3..07a0c250f 100644 --- a/content/getting-started/kotlintutorial.md +++ b/content/getting-started/kotlintutorial.md @@ -1,24 +1,23 @@ +++ -title = "Protocol Buffer Basics: Kotlin" +title = "Protobuf Basics: Kotlin" weight = 260 linkTitle = "Kotlin" -description = "A basic Kotlin programmers introduction to working with protocol buffers." +description = "A basic Kotlin programmers introduction to working with Protobuf." type = "docs" +++ This tutorial provides a basic Kotlin programmer's introduction to working with -protocol buffers, using the -[proto3](/programming-guides/proto3) version of the -protocol buffers language. By walking through creating a simple example +Protobuf, using the [proto3](/programming-guides/proto3) +version of the Protobuf language. By walking through creating a simple example application, it shows you how to - Define message formats in a `.proto` file. -- Use the protocol buffer compiler. -- Use the Kotlin protocol buffer API to write and read messages. +- Use the Protobuf compiler. +- Use the Kotlin Protobuf API to write and read messages. -This isn't a comprehensive guide to using protocol buffers in Kotlin. For more -detailed reference information, see the -[Protocol Buffer Language Guide](/programming-guides/proto3), +This isn't a comprehensive guide to using Protobuf in Kotlin. For more detailed +reference information, see the +[Protobuf Language Guide](/programming-guides/proto3), the [Kotlin API Reference](/reference/kotlin/api-docs), the [Kotlin Generated Code Guide](/reference/kotlin/kotlin-generated), @@ -38,7 +37,7 @@ ways to solve this problem: - Use kotlinx.serialization. This does not work very well if you need to share data with applications written in C++ or Python. kotlinx.serialization has a [protobuf mode](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/formats#protobuf-experimental), - but this does not offer the full features of protocol buffers. + but this does not offer the full features of Protobuf. - You can invent an ad-hoc way to encode the data items into a single string -- such as encoding 4 ints as "12:3:-23:67". This is a simple and flexible approach, although it does require writing one-off encoding and @@ -52,23 +51,22 @@ ways to solve this problem: Also, navigating an XML DOM tree is considerably more complicated than navigating simple fields in a class normally would be. -Protocol buffers are the flexible, efficient, automated solution to solve -exactly this problem. With protocol buffers, you write a `.proto` description of -the data structure you wish to store. From that, the protocol buffer compiler -creates a class that implements automatic encoding and parsing of the protocol -buffer data with an efficient binary format. The generated class provides -getters and setters for the fields that make up a protocol buffer and takes care -of the details of reading and writing the protocol buffer as a unit. -Importantly, the protocol buffer format supports the idea of extending the -format over time in such a way that the code can still read data encoded with -the old format. +Protobuf is the flexible, efficient, automated solution to solve exactly this +problem. With Protobuf, you write a `.proto` description of the data structure +you wish to store. From that, the Protobuf compiler creates a class that +implements automatic encoding and parsing of the Protobuf data with an efficient +binary format. The generated class provides getters and setters for the fields +that make up a Protobuf message and takes care of the details of reading and +writing the message as a unit. Importantly, the Protobuf format supports the +idea of extending the format over time in such a way that the code can still +read data encoded with the old format. ## Where to Find the Example Code {#example-code} Our example is a set of command-line applications for managing an address book -data file, encoded using protocol buffers. The command `add_person_kotlin` adds -a new entry to the data file. The command `list_people_kotlin` parses the data -file and prints the data to the console. +data file, encoded using Protobuf. The command `add_person_kotlin` adds a new +entry to the data file. The command `list_people_kotlin` parses the data file +and prints the data to the console. You can find the complete example in the [examples directory](https://github.com/protocolbuffers/protobuf/tree/master/examples) @@ -154,20 +152,20 @@ returns that field's default value. If a field is `repeated`, the field may be repeated any number of times (including zero). The order of the repeated values will be preserved in the -protocol buffer. Think of repeated fields as dynamically sized arrays. +Protobuf message. Think of repeated fields as dynamically sized arrays. You'll find a complete guide to writing `.proto` files -- including all the possible field types -- in the -[Protocol Buffer Language Guide](/programming-guides/proto3). -Don't go looking for facilities similar to class inheritance, though -- protocol -buffers don't do that. +[Protobuf Language Guide](/programming-guides/proto3). +Don't go looking for facilities similar to class inheritance, though -- Protobuf +doesn't do that. -## Compiling Your Protocol Buffers {#compiling-protocol-buffers} +## Compiling Your Protobuf Schema {#compiling-protocol-buffers} Now that you have a `.proto`, the next thing you need to do is generate the classes you'll need to read and write `AddressBook` (and hence `Person` and -`PhoneNumber`) messages. To do this, you need to run the protocol buffer -compiler `protoc` on your `.proto`: +`PhoneNumber`) messages. To do this, you need to run the Protobuf compiler +`protoc` on your `.proto`: 1. If you haven't installed the compiler, [download the package](/downloads) and follow the @@ -192,15 +190,15 @@ your specified Java destination directory, containing a few generated `.java` files and a `com/example/tutorial/protos/` subdirectory in your specified Kotlin destination directory, containing a few generated `.kt` files. -## The Protocol Buffer API {#protobuf-api} +## The Protobuf API {#protobuf-api} -The protocol buffer compiler for Kotlin generates Kotlin APIs that add to the -existing APIs generated for protocol buffers for Java. This ensures that -codebases written in a mix of Java and Kotlin can interact with the same -protocol buffer message objects without any special handling or conversion. +The Protobuf compiler for Kotlin generates Kotlin APIs that add to the existing +APIs generated for Java. This ensures that codebases written in a mix of Java +and Kotlin can interact with the same Protobuf message objects without any +special handling or conversion. -Protocol buffers for other Kotlin compilation targets, such as JavaScript and -native, are not currently supported. +Protobuf for other Kotlin compilation targets, such as JavaScript and native, is +not currently supported. Compiling `addressbook.proto` gives you the following APIs in Java: @@ -223,10 +221,10 @@ You can read more about the details of exactly what's generated in the ## Writing a Message {#writing-a-message} -Now let's try using your protocol buffer classes. The first thing you want your -address book application to be able to do is write personal details to your -address book file. To do this, you need to create and populate instances of your -protocol buffer classes and then write them to an output stream. +Now let's try using your Protobuf classes. The first thing you want your address +book application to be able to do is write personal details to your address book +file. To do this, you need to create and populate instances of your Protobuf +classes and then write them to an output stream. Here is a program which reads an `AddressBook` from a file, adds one new `Person` to it based on user input, and writes the new `AddressBook` back out to @@ -340,19 +338,18 @@ fun main(args: List) { } ``` -## Extending a Protocol Buffer {#extending-a-protobuf} +## Extending a Protobuf Message {#extending-a-protobuf} -Sooner or later after you release the code that uses your protocol buffer, you -will undoubtedly want to "improve" the protocol buffer's definition. If you want -your new buffers to be backwards-compatible, and your old buffers to be +Sooner or later after you release the code that uses your Protobuf message, you +will undoubtedly want to "improve" the message's definition. If you want your +new messages to be backwards-compatible, and your old messages to be forward-compatible -- and you almost certainly do want this -- then there are -some rules you need to follow. In the new version of the protocol buffer: +some rules you need to follow. In the new version of the message: - you *must not* change the tag numbers of any existing fields. - you *may* delete fields. - you *may* add new fields but you must use fresh tag numbers (i.e. tag - numbers that were never used in this protocol buffer, not even by deleted - fields). + numbers that were never used in this message, not even by deleted fields). (There are [some exceptions](/programming-guides/proto3#updating) to diff --git a/content/getting-started/pythontutorial.md b/content/getting-started/pythontutorial.md index 9718dda05..aea078d5b 100644 --- a/content/getting-started/pythontutorial.md +++ b/content/getting-started/pythontutorial.md @@ -1,24 +1,24 @@ +++ -title = "Protocol Buffer Basics: Python" +title = "Protobuf Basics: Python" weight = 270 linkTitle = "Python" -description = "A basic Python programmers introduction to working with protocol buffers." +description = "A basic Python programmers introduction to working with Protobuf." type = "docs" +++ This tutorial provides a basic Python programmer's introduction to working with -protocol buffers. By walking through creating a simple example application, it -shows you how to +Protobuf. By walking through creating a simple example application, it shows you +how to - Define message formats in a `.proto` file. -- Use the protocol buffer compiler. -- Use the Python protocol buffer API to write and read messages. +- Use the Protobuf compiler. +- Use the Python Protobuf API to write and read messages. -This isn't a comprehensive guide to using protocol buffers in Python. For more -detailed reference information, see the -[Protocol Buffer Language Guide (proto2)](/programming-guides/proto2), +This isn't a comprehensive guide to using Protobuf in Python. For more detailed +reference information, see the +[Protobuf Language Guide (proto2)](/programming-guides/proto2), the -[Protocol Buffer Language Guide (proto3)](/programming-guides/proto3), +[Protobuf Language Guide (proto3)](/programming-guides/proto3), the [Python API Reference](https://googleapis.dev/python/protobuf/latest/), the [Python Generated Code Guide](/reference/python/python-generated), and the @@ -51,16 +51,16 @@ ways to solve this problem: Also, navigating an XML DOM tree is considerably more complicated than navigating simple fields in a class normally would be. -Instead of these options, you can use protocol buffers. Protocol buffers are the -flexible, efficient, automated solution to solve exactly this problem. With -protocol buffers, you write a `.proto` description of the data structure you -wish to store. From that, the protocol buffer compiler creates a class that -implements automatic encoding and parsing of the protocol buffer data with an -efficient binary format. The generated class provides getters and setters for -the fields that make up a protocol buffer and takes care of the details of -reading and writing the protocol buffer as a unit. Importantly, the protocol -buffer format supports the idea of extending the format over time in such a way -that the code can still read data encoded with the old format. +Instead of these options, you can use Protobuf. Protobuf is the flexible, +efficient, automated solution to solve exactly this problem. With Protobuf, you +write a `.proto` description of the data structure you wish to store. From that, +the Protobuf compiler creates a class that implements automatic encoding and +parsing of the Protobuf data with an efficient binary format. The generated +class provides getters and setters for the fields that make up a Protobuf +message and takes care of the details of reading and writing the message as a +unit. Importantly, the Protobuf format supports the idea of extending the format +over time in such a way that the code can still read data encoded with the old +format. ## Where to Find the Example Code {#example-code} @@ -112,8 +112,8 @@ The `.proto` file starts with a package declaration, which helps to prevent naming conflicts between different projects. In Python, packages are normally determined by directory structure, so the `package` you define in your `.proto` file will have no effect on the generated code. However, you should still -declare one to avoid name collisions in the Protocol Buffers name space as well -as in non-Python languages. +declare one to avoid name collisions in the Protobuf name space as well as in +non-Python languages. Next, you have your message definitions. A message is just an aggregate containing a set of typed fields. Many standard simple data types are available @@ -137,16 +137,16 @@ for this optimization. You'll find a complete guide to writing `.proto` files -- including all the possible field types -- in the -[Protocol Buffer Language Guide](/programming-guides/editions). -Don't go looking for facilities similar to class inheritance, though -- protocol -buffers don't do that. +[Protobuf Language Guide](/programming-guides/editions). +Don't go looking for facilities similar to class inheritance, though -- Protobuf +doesn't do that. -## Compiling Your Protocol Buffers {#compiling-protocol-buffers} +## Compiling Your Protobuf Schema {#compiling-protocol-buffers} Now that you have a `.proto`, the next thing you need to do is generate the classes you'll need to read and write `AddressBook` (and hence `Person` and -`PhoneNumber`) messages. To do this, you need to run the protocol buffer -compiler `protoc` on your `.proto`: +`PhoneNumber`) messages. To do this, you need to run the Protobuf compiler +`protoc` on your `.proto`: 1. If you haven't installed the compiler, [download the package](/downloads) and follow the @@ -170,13 +170,13 @@ compiler `protoc` on your `.proto`: This generates `addressbook_pb2.py` (or `addressbook_pb2.pyi`) in your specified destination directory. -## The Protocol Buffer API {#protobuf-api} +## The Protobuf API {#protobuf-api} -Unlike when you generate Java and C++ protocol buffer code, the Python protocol -buffer compiler doesn't generate your data access code for you directly. Instead -(as you'll see if you look at `addressbook_pb2.py`) it generates special -descriptors for all your messages, enums, and fields, and some mysteriously -empty classes, one for each message type: +Unlike when you generate Java and C++ Protobuf code, the Python Protobuf +compiler doesn't generate your data access code for you directly. Instead (as +you'll see if you look at `addressbook_pb2.py`) it generates special descriptors +for all your messages, enums, and fields, and some mysteriously empty classes, +one for each message type: ```python import google3 @@ -278,8 +278,8 @@ These methods implement the `Message` interface. For more information, see the ### Parsing and Serialization {#parsing-serialization} -Finally, each protocol buffer class has methods for writing and reading messages -of your chosen type using the protocol buffer +Finally, each Protobuf class has methods for writing and reading messages of +your chosen type using the Protobuf [binary format](/programming-guides/encoding). These include: @@ -318,12 +318,12 @@ new_person = addressbook_pb2.Person() json_format.Parse(json_string, new_person) ``` -{{% alert title="Important" color="warning" %}} **Protocol Buffers and Object Oriented Design** -Protocol buffer classes are basically data holders (like structs in C) that -don't provide additional functionality; they don't make good first class -citizens in an object model. If you want to add richer behavior to a generated -class, the best way to do this is to wrap the generated protocol buffer class in -an application-specific class. Wrapping protocol buffers is also a good idea if +{{% alert title="Important" color="warning" %}} **Protobuf and Object Oriented Design** +Protobuf classes are basically data holders (like structs in C) that don't +provide additional functionality; they don't make good first class citizens in +an object model. If you want to add richer behavior to a generated class, the +best way to do this is to wrap the generated Protobuf class in an +application-specific class. Wrapping Protobuf messages is also a good idea if you don't have control over the design of the `.proto` file (if, say, you're reusing one from another project). In that case, you can use the wrapper class to craft an interface better suited to the unique environment of your @@ -334,10 +334,10 @@ practice anyway. {{% /alert %}} ## Writing a Message {#writing-a-message} -Now let's try using your protocol buffer classes. The first thing you want your -address book application to be able to do is write personal details to your -address book file. To do this, you need to create and populate instances of your -protocol buffer classes and then write them to an output stream. +Now let's try using your Protobuf classes. The first thing you want your address +book application to be able to do is write personal details to your address book +file. To do this, you need to create and populate instances of your Protobuf +classes and then write them to an output stream. Here is a program which reads an `AddressBook` from a file, adds one new `Person` to it based on user input, and writes the new `AddressBook` back out to @@ -445,20 +445,20 @@ with open(sys.argv[1], "rb") as f: ListPeople(address_book) ``` -## Extending a Protocol Buffer {#extending-a-protobuf} +## Extending a Protobuf Message {#extending-a-protobuf} -Sooner or later after you release the code that uses your protocol buffer, you -will undoubtedly want to "improve" the protocol buffer's definition. If you want -your new buffers to be backwards-compatible, and your old buffers to be +Sooner or later after you release the code that uses your Protobuf message, you +will undoubtedly want to "improve" the message's definition. If you want your +new messages to be backwards-compatible, and your old messages to be forward-compatible -- and you almost certainly do want this -- then there are -some rules you need to follow. In the new version of the protocol buffer: +some rules you need to follow. In the new version of the message: - you *must not* change the tag numbers of any existing fields. - you *must not* add or delete any required fields. - you *may* delete optional or repeated fields. - you *may* add new optional or repeated fields but you must use fresh tag - numbers (that is, tag numbers that were never used in this protocol buffer, - not even by deleted fields). + numbers (that is, tag numbers that were never used in this message, not even + by deleted fields). (There are [some exceptions](/programming-guides/proto2#updating) to @@ -480,10 +480,10 @@ or never set at all (by old code) since there is no `HasField` check for it. ## Advanced Usage {#advanced-usage} -Protocol buffers have uses that go beyond simple accessors and serialization. Be -sure to explore the +Protobuf has uses that go beyond simple accessors and serialization. Be sure to +explore the [Python API reference](https://googleapis.dev/python/protobuf/latest/) to see -what else you can do with them. +what else you can do with it. One key feature provided by protocol message classes is *reflection*. You can iterate over the fields of a message and manipulate their values without writing @@ -493,8 +493,8 @@ as XML or JSON (see [Parsing and Serialization](#parsing-serialization) for an example). A more advanced use of reflection might be to find differences between two messages of the same type, or to develop a sort of "regular expressions for protocol messages" in which you can write expressions that match certain message -contents. If you use your imagination, it's possible to apply Protocol Buffers -to a much wider range of problems than you might initially expect! +contents. If you use your imagination, it's possible to apply Protobuf to a much +wider range of problems than you might initially expect! Reflection is provided as part of the [`Message` interface](https://googleapis.dev/python/protobuf/latest/google/protobuf/message.html#google.protobuf.message.Message). diff --git a/content/history.md b/content/history.md index 4e4c1b87b..16eb9044f 100644 --- a/content/history.md +++ b/content/history.md @@ -1,39 +1,38 @@ +++ title = "History" weight = 1020 -description = "A brief history behind the creation of protocol buffers." +description = "A brief history behind the creation of Protobuf." type = "docs" +++ -Understanding -why protobuf was created and the decisions that changed it over time can help -you to better use the features of the tool. +Understanding why +Protobuf was created and the decisions that changed it over time can help you to +better use the features of the tool. -## Why Did You Release Protocol Buffers? {#why} +## Why Did You Release Protobuf? {#why} -There are several reasons that we released Protocol Buffers. +There are several reasons that we released Protobuf. -Protocol buffers are used by many projects inside Google. We had other projects -we wanted to release as open source that use protocol buffers, so to do this, we -needed to release protocol buffers first. In fact, bits of the technology had -already found their way into the open; if you dig into the code for Google -AppEngine, you might find some of it. +Protobuf is used by many projects inside Google. We had other projects we wanted +to release as open source that use Protobuf, so to do this, we needed to release +Protobuf first. In fact, bits of the technology had already found their way into +the open; if you dig into the code for Google AppEngine, you might find some of +it. -We wanted to provide public APIs that accept protocol buffers as well as XML, -both because it is more efficient and because we convert that XML to protocol -buffers on our end, anyway. +We wanted to provide public APIs that accept Protobuf as well as XML, both +because it is more efficient and because we convert that XML to Protobuf on our +end, anyway. -We thought that people outside Google might find protocol buffers useful. -Getting protocol buffers into a form we were happy to release was a fun side -project. +We thought that people outside Google might find Protobuf useful. Getting +Protobuf into a form we were happy to release was a fun side project. ## Why Is the First Release Version 2? What Happened to Version 1? {#version-1} -The initial version of protocol buffers ("Proto1") was developed starting in -early 2001 and evolved over the course of many years, sprouting new features -whenever someone needed them and was willing to do the work to create them. Like -anything created in such a way, it was a bit of a mess. We came to the -conclusion that it would not be feasible to release the code as it was. +The initial version of Protobuf ("Proto1") was developed starting in early 2001 +and evolved over the course of many years, sprouting new features whenever +someone needed them and was willing to do the work to create them. Like anything +created in such a way, it was a bit of a mess. We came to the conclusion that it +would not be feasible to release the code as it was. Version 2 ("Proto2") was a complete rewrite, though it kept most of the design and used many of the implementation ideas from Proto1. Some features were added, @@ -43,8 +42,8 @@ any dependencies on Google libraries that were not yet open-sourced. ## Why the Name "Protocol Buffers"? {#name} The name originates from the early days of the format, before we had the -protocol buffer compiler to generate classes for us. At the time, there was a -class called `ProtocolBuffer` that actually acted as a buffer for an individual +Protobuf compiler to generate classes for us. At the time, there was a class +called `ProtocolBuffer` that actually acted as a buffer for an individual method. Users would add tag/value pairs to this buffer individually by calling methods like `AddValue(tag, value)`. The raw bytes were stored in a buffer that could then be written out once the message had been constructed. @@ -57,10 +56,10 @@ in-memory object representing the parsed message. ## What About Proto3 and Editions? {#proto3} -In 2023, we introduced Protocol Buffers Editions to allow for a more granular -control over features and to move away from the "all or nothing" approach of -`proto2` and `proto3`. With Editions, you can now explicitly specify which -features you want to use in your `.proto` files. +In 2023, we introduced Protobuf Editions to allow for a more granular control +over features and to move away from the "all or nothing" approach of `proto2` +and `proto3`. With Editions, you can now explicitly specify which features you +want to use in your `.proto` files. For example, to use the 2023 edition, you would add the following to your `.proto` file: @@ -73,20 +72,20 @@ There will be a transitional period during which `proto2`, `proto3`, and Editions coexist. For more information on Editions, see the [Protobuf Editions Overview](/editions/overview). -## Does Google Have Any Patents on Protocol Buffers? {#patents} +## Does Google Have Any Patents on Protobuf? {#patents} -Google currently has no issued patents on protocol buffers, and we are happy to -address any concerns around protocol buffers and patents that people may have. +Google currently has no issued patents on Protobuf, and we are happy to address +any concerns around Protobuf and patents that people may have. -## How Do Protocol Buffers Differ from ASN.1, COM, CORBA, and Thrift? {#differ} +## How Does Protobuf Differ from ASN.1, COM, CORBA, and Thrift? {#differ} We think all of these systems have strengths and weaknesses. Google relies on -protocol buffers internally and they are a vital component of our success, but -that doesn't mean they are the ideal solution for every problem. You should -evaluate each alternative in the context of your own project. +Protobuf internally and it is a vital component of our success, but that doesn't +mean it is the ideal solution for every problem. You should evaluate each +alternative in the context of your own project. It is worth noting, though, that several of these technologies define both an -interchange format and an RPC (remote procedure call) protocol. Protocol buffers -are just an interchange format. They could easily be used for RPC—and, -indeed, they do have limited support for defining RPC services—but they -are not tied to any one RPC implementation or protocol. +interchange format and an RPC (remote procedure call) protocol. Protobuf is just +an interchange format. It could easily be used for RPC—and, indeed, it +does have limited support for defining RPC services—but it is not tied to +any one RPC implementation or protocol. diff --git a/content/installation.md b/content/installation.md index f6bc3ce38..6ded35bc2 100644 --- a/content/installation.md +++ b/content/installation.md @@ -1,13 +1,13 @@ +++ -title = "Protocol Buffer Compiler Installation" +title = "Protobuf Compiler Installation" weight = 15 -description = "How to install the protocol buffer compiler." +description = "How to install the Protobuf compiler." type = "docs" no_list = "true" linkTitle = "Protoc Installation" +++ -The protocol buffer compiler, `protoc`, is used to compile `.proto` files, which +The Protobuf compiler, `protoc`, is used to compile `.proto` files, which contain service and message definitions. Choose one of the methods given below to install `protoc`. @@ -94,4 +94,4 @@ Linux, macOS, or Windows using the following commands. If you'd like to build the protocol compiler from sources, or access older versions of the pre-compiled binaries, see -[Download Protocol Buffers](https://protobuf.dev/downloads). +[Download Protobuf](https://protobuf.dev/downloads). diff --git a/content/news/2022-05-06.md b/content/news/2022-05-06.md index fbf00530b..d15b44d2b 100644 --- a/content/news/2022-05-06.md +++ b/content/news/2022-05-06.md @@ -2,19 +2,19 @@ title = "Changes announced May 6, 2022" linkTitle = "May 6, 2022" toc_hide = "true" -description = "Changes announced for Protocol Buffers on May 6, 2022." +description = "Changes announced for Protobuf on May 6, 2022." type = "docs" +++ ## Versioning {#versioning} We changed our versioning scheme to enable more-nimble updates to -language-specific parts of Protocol Buffers. In the new scheme, each language -has its own major version that can be incremented independently of other -languages, as covered later in this topic with the Python release. The minor and -patch versions, however, will remain coupled. This allows us to introduce -breaking changes into some languages without requiring a bump of the major -version in languages that do not experience a breaking change. +language-specific parts of Protobuf. In the new scheme, each language has its +own major version that can be incremented independently of other languages, as +covered later in this topic with the Python release. The minor and patch +versions, however, will remain coupled. This allows us to introduce breaking +changes into some languages without requiring a bump of the major version in +languages that do not experience a breaking change. The first instance of this new versioning scheme is the new version of the Python API, 4.21.0, which follows the preceding version, 3.20.1. Other language @@ -22,8 +22,8 @@ APIs will be released as 3.21.0. ## Python Updates {#python-updates} -We made some changes in Python language support in Protocol Buffers. Version -4.21.0 is a new major version, following 3.20.1. The new version is based on the +We made some changes in Python language support in Protobuf. Version 4.21.0 is a +new major version, following 3.20.1. The new version is based on the [upb library](https://github.com/protocolbuffers/upb), and offers significantly better parsing performance than previous releases, especially for large payloads. It also includes prebuilt binary modules for Apple silicon for @@ -49,13 +49,13 @@ The new release does contain some breaking changes. Specifically: ## JavaScript Support {#javascript} -We moved some things around for Protocol Buffer support of JavaScript to allow +We moved some things around for Protobuf support of JavaScript to allow JavaScript to evolve and release independently of the main repo. Specifically, we decoupled the language support from the [main project](https://github.com/protocolbuffers/protobuf) and moved it into its [own repository](https://github.com/protocolbuffers/protobuf-javascript). -If you have created any pull requests related to JavaScript support in Protocol -Buffers that you'd still like to merge, feel free to replicate those against the +If you have created any pull requests related to JavaScript support in Protobuf +that you'd still like to merge, feel free to replicate those against the JavaScript repository. We will transfer GitHub issues automatically. diff --git a/content/news/2022-07-06.md b/content/news/2022-07-06.md index 870dab7f9..83709be85 100644 --- a/content/news/2022-07-06.md +++ b/content/news/2022-07-06.md @@ -2,7 +2,7 @@ title = "Changes announced July 6, 2022" linkTitle = "July 6, 2022" toc_hide = "true" -description = "Changes announced for Protocol Buffers on July 6, 2022." +description = "Changes announced for Protobuf on July 6, 2022." type = "docs" +++ @@ -10,5 +10,5 @@ type = "docs" Google released its [OSS Library Breaking Change Policy](https://opensource.google/documentation/policies/library-breaking-change), -which some Google-sponsored open source projects have opted into. Protocol -buffers has adopted this policy. +which some Google-sponsored open source projects have opted into. Protobuf has +adopted this policy. diff --git a/content/news/2022-08-03.md b/content/news/2022-08-03.md index eb1817540..0a6bb06b7 100644 --- a/content/news/2022-08-03.md +++ b/content/news/2022-08-03.md @@ -2,7 +2,7 @@ title = "Changes announced August 3, 2022" linkTitle = "August 3, 2022" toc_hide = "true" -description = "Changes announced for Protocol Buffers on August 3, 2022." +description = "Changes announced for Protobuf on August 3, 2022." type = "docs" +++ @@ -32,9 +32,9 @@ we are planning a major version bump for C++. We plan to make some changes to the assets that we release starting with our 22.x release line. The following sections outline the set of breaking changes that we plan to -include in the 22.0 release of protocol buffers. Note that plans can and do -change. These are potential breaking changes to be aware of, but they may not -happen in this particular release, or they may not happen at all. +include in the 22.0 release of Protobuf. Note that plans can and do change. +These are potential breaking changes to be aware of, but they may not happen in +this particular release, or they may not happen at all. ### Adding C++20 Support {#c20-support} @@ -55,7 +55,7 @@ we plan to drop C++11 support. This is a breaking change. Per our [build systems support policy](https://opensource.google/documentation/policies/cplusplus-support#3_build_systems), we plan to drop autotools support. This is a breaking change. After autotools -support is dropped, protobuf will support only CMake and Bazel. +support is dropped, Protobuf will support only CMake and Bazel. ### Dropping Support for PHP <7.4 {#php-74} @@ -66,7 +66,7 @@ breaking change since these versions are already EOL in the broader ecosystem. ### Adding an Abseil Dependency {#abseil-dep} -In order to reduce the Google vs. OSS differences between protobuf and to +In order to reduce the Google vs. OSS differences between Protobuf and to simplify our own project, we plan to take a formal dependency on Abseil. In time, we plan to start using Abseil types in our public APIs, but simply adding the dependency is a breaking change. diff --git a/content/news/2023-04-11.md b/content/news/2023-04-11.md index e8d04f25c..af4d249f9 100644 --- a/content/news/2023-04-11.md +++ b/content/news/2023-04-11.md @@ -2,7 +2,7 @@ title = "Changes announced April 11, 2023" linkTitle = "April 11, 2023" toc_hide = "true" -description = "Changes announced for Protocol Buffers on April 11, 2023." +description = "Changes announced for Protobuf on April 11, 2023." type = "docs" +++ diff --git a/content/news/2023-04-20.md b/content/news/2023-04-20.md index e36edee46..12096d2ea 100644 --- a/content/news/2023-04-20.md +++ b/content/news/2023-04-20.md @@ -2,7 +2,7 @@ title = "Changes announced April 20, 2023" linkTitle = "April 20, 2023" toc_hide = "true" -description = "Changes announced for Protocol Buffers on April 20, 2023." +description = "Changes announced for Protobuf on April 20, 2023." type = "docs" +++ diff --git a/content/news/2023-04-28.md b/content/news/2023-04-28.md index ef77548cb..30151dfcf 100644 --- a/content/news/2023-04-28.md +++ b/content/news/2023-04-28.md @@ -2,7 +2,7 @@ title = "Changes announced April 28, 2023" linkTitle = "April 28, 2023" toc_hide = "true" -description = "Changes announced for Protocol Buffers on April 28, 2023." +description = "Changes announced for Protobuf on April 28, 2023." type = "docs" +++ diff --git a/content/news/2023-06-29.md b/content/news/2023-06-29.md index 2cfc5b326..65365e186 100644 --- a/content/news/2023-06-29.md +++ b/content/news/2023-06-29.md @@ -2,7 +2,7 @@ title = "Changes Announced on June 29, 2023" linkTitle = "June 29, 2023" toc_hide = "true" -description = "Changes announced for Protocol Buffers on June 29, 2023." +description = "Changes announced for Protobuf on June 29, 2023." type = "docs" +++ @@ -11,15 +11,15 @@ type = "docs" ## Protobuf Editions {#editions} 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. -Editions enable the language to evolve incrementally over time. +for Protobuf. 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. Editions enable +the language to evolve incrementally over time. Instead of the hardcoded behaviors in older versions, editions will represent a collection of “features” with a default value (behavior) per feature, which you can override. Features are options on a file, message, field, enum, and so on -that specify the behavior of protoc, the code generators, and protobuf runtimes. +that specify the behavior of protoc, the code generators, and Protobuf runtimes. You can explicitly override the desired behavior at those different levels (file, message, field, ...) when your needs don't match the default behavior for the edition you've selected. diff --git a/content/news/2023-07-06.md b/content/news/2023-07-06.md index 08a8698ce..40633ba83 100644 --- a/content/news/2023-07-06.md +++ b/content/news/2023-07-06.md @@ -2,7 +2,7 @@ title = "Changes Announced on July 6, 2023" linkTitle = "July 6, 2023" toc_hide = "true" -description = "Changes announced for Protocol Buffers on July 6, 2023." +description = "Changes announced for Protobuf on July 6, 2023." type = "docs" +++ @@ -14,7 +14,7 @@ we will be dropping support for PHP 7.4 and lower. This means the minimum supported PHP version is 8.0. If you are running an older version of PHP, you can install a previous release -of the protobuf PHP extension by running `pecl install protobuf-3.23.3`. +of the Protobuf PHP extension by running `pecl install protobuf-3.23.3`. ## Dropping Ruby 2.6 Support diff --git a/content/news/2023-07-17.md b/content/news/2023-07-17.md index 98a66acba..85915aada 100644 --- a/content/news/2023-07-17.md +++ b/content/news/2023-07-17.md @@ -2,7 +2,7 @@ title = "Changes Announced on July 17, 2023" linkTitle = "July 17, 2023" toc_hide = "true" -description = "Changes announced for Protocol Buffers on July 17, 2023." +description = "Changes announced for Protobuf on July 17, 2023." type = "docs" +++ diff --git a/content/news/2023-08-09.md b/content/news/2023-08-09.md index 667a87ffc..cf4c812ba 100644 --- a/content/news/2023-08-09.md +++ b/content/news/2023-08-09.md @@ -2,7 +2,7 @@ title = "Changes Announced on August 9, 2023" linkTitle = "August 9, 2023" toc_hide = "true" -description = "Changes announced for Protocol Buffers on August 9, 2023." +description = "Changes announced for Protobuf on August 9, 2023." type = "docs" +++ diff --git a/content/news/2023-08-15.md b/content/news/2023-08-15.md index 4bd7bae87..803a548bb 100644 --- a/content/news/2023-08-15.md +++ b/content/news/2023-08-15.md @@ -4,7 +4,7 @@ title = "Changes Announced on August 15, 2023" linkTitle = "August 15, 2023" toc_hide = "true" -description = "Changes announced for Protocol Buffers on August 15, 2023." +description = "Changes announced for Protobuf on August 15, 2023." type = "docs" +++ diff --git a/content/news/2023-09-15.md b/content/news/2023-09-15.md index 1a1de6f57..63c1d4ceb 100644 --- a/content/news/2023-09-15.md +++ b/content/news/2023-09-15.md @@ -2,21 +2,21 @@ title = "Changes announced on September 15, 2023" linkTitle = "September 15, 2023" toc_hide = "true" -description = "Changes announced for Protocol Buffers on September 15, 2023." +description = "Changes announced for Protobuf on September 15, 2023." type = "docs" +++ ## μpb Moving to the Protobuf Git Repository Starting with the v25 release, μpb now lives in the -[protobuf repo](https://github.com/protocolbuffers/protobuf) instead +[Protobuf repo](https://github.com/protocolbuffers/protobuf) instead of in its [former location](https://github.com/protocolbuffers/upb) in a separate repo. All μpb development going forward will take place only in the new location. The merger of the two repos will simplify and speed up our development process -by removing the need to update pinned version dependencies between protobuf and -μpb. Changes to μpb now take effect immediately in protobuf code and vice versa, +by removing the need to update pinned version dependencies between Protobuf and +μpb. Changes to μpb now take effect immediately in Protobuf code and vice versa, without the need for a manual upgrade step. We expect that most users will not need to take much, if any, action to @@ -25,7 +25,7 @@ implementations, but you will most likely not notice the change unless you have code that refers to μpb directly. If you refer to μpb from a Bazel project, you will need to update μpb references -to point to protobuf instead (for example, replace `@upb` with +to point to Protobuf instead (for example, replace `@upb` with `@com_google_protobuf`). We are keeping μpb file paths and Bazel targets the same to minimize the need for additional changes, but there are two exceptions: diff --git a/content/news/2023-10-10.md b/content/news/2023-10-10.md index 950fb649d..c32957b82 100644 --- a/content/news/2023-10-10.md +++ b/content/news/2023-10-10.md @@ -2,7 +2,7 @@ title = "Changes announced on October 10, 2023" linkTitle = "October 10, 2023" toc_hide = "true" -description = "Changes announced for Protocol Buffers on October 10, 2023." +description = "Changes announced for Protobuf on October 10, 2023." type = "docs" +++ diff --git a/content/news/2023-12-05.md b/content/news/2023-12-05.md index d8d044d90..4c68047ee 100644 --- a/content/news/2023-12-05.md +++ b/content/news/2023-12-05.md @@ -2,7 +2,7 @@ title = "Changes announced on December 5, 2023" linkTitle = "December 5, 2023" toc_hide = "true" -description = "Changes announced for Protocol Buffers on December 5, 2023." +description = "Changes announced for Protobuf on December 5, 2023." type = "docs" +++ @@ -13,9 +13,9 @@ In v26, we are planning a major version bump for Java per our [version support policy](/support/version-support#java). The following sections outline the set of breaking changes that we plan to -include in the 26.0 release of protocol buffers. Note that plans can and do -change. These are potential breaking changes to be aware of, but they may not -happen in this particular release, or they may not happen at all. +include in the 26.0 release of Protobuf. Note that plans can and do change. +These are potential breaking changes to be aware of, but they may not happen in +this particular release, or they may not happen at all. ### Poison Pilling Gencode / Runtime Mismatches diff --git a/content/news/2023-12-13.md b/content/news/2023-12-13.md index 0d4912111..1dd246d99 100644 --- a/content/news/2023-12-13.md +++ b/content/news/2023-12-13.md @@ -2,7 +2,7 @@ title = "Changes announced on December 13, 2023" linkTitle = "December 13, 2023" toc_hide = "true" -description = "Changes announced for Protocol Buffers on December 13, 2023." +description = "Changes announced for Protobuf on December 13, 2023." type = "docs" +++ @@ -13,9 +13,9 @@ In v26, we are planning a major version bump for C++ as per our [version support policy](/support/version-support#cpp-tooling). The following sections outline the set of breaking changes that we plan to -include in the 26.0 release of protocol buffers. Note that plans can and do -change. These are potential breaking changes to be aware of, but they may not -happen in this particular release, or they may not happen at all. +include in the 26.0 release of Protobuf. Note that plans can and do change. +These are potential breaking changes to be aware of, but they may not happen in +this particular release, or they may not happen at all. ### Remove deprecated clear APIs on repeated fields diff --git a/content/news/2023-12-27.md b/content/news/2023-12-27.md index 46a9c12ef..c5fdb150c 100644 --- a/content/news/2023-12-27.md +++ b/content/news/2023-12-27.md @@ -2,7 +2,7 @@ title = "Changes announced on December 27, 2023" linkTitle = "December 27, 2023" toc_hide = "true" -description = "Changes announced for Protocol Buffers on December 27, 2023." +description = "Changes announced for Protobuf on December 27, 2023." type = "docs" +++ diff --git a/content/news/2024-01-05.md b/content/news/2024-01-05.md index dfe63c207..07d7d84ac 100644 --- a/content/news/2024-01-05.md +++ b/content/news/2024-01-05.md @@ -2,7 +2,7 @@ title = "Changes announced January 5, 2024" linkTitle = "January 5, 2024" toc_hide = "true" -description = "Changes announced for Protocol Buffers on January 5, 2024." +description = "Changes announced for Protobuf on January 5, 2024." type = "docs" +++ diff --git a/content/news/2024-01-31.md b/content/news/2024-01-31.md index ea8bffff2..e03507162 100644 --- a/content/news/2024-01-31.md +++ b/content/news/2024-01-31.md @@ -2,7 +2,7 @@ title = "Changes announced January 31, 2024" linkTitle = "January 31, 2024" toc_hide = "true" -description = "Changes announced for Protocol Buffers on January 31, 2024." +description = "Changes announced for Protobuf on January 31, 2024." type = "docs" +++ diff --git a/content/news/2024-02-05.md b/content/news/2024-02-05.md index 0e5316234..7dbcbc7bb 100644 --- a/content/news/2024-02-05.md +++ b/content/news/2024-02-05.md @@ -2,7 +2,7 @@ title = "Changes announced February 5, 2024" linkTitle = "February 5, 2024" toc_hide = "true" -description = "Changes announced for Protocol Buffers on February 5, 2024." +description = "Changes announced for Protobuf on February 5, 2024." type = "docs" +++ diff --git a/content/news/2024-02-27.md b/content/news/2024-02-27.md index b80268a90..51d45ba8d 100644 --- a/content/news/2024-02-27.md +++ b/content/news/2024-02-27.md @@ -2,7 +2,7 @@ title = "Changes Announced on February 27, 2024" linkTitle = "February 27, 2024" toc_hide = "true" -description = "Changes announced for Protocol Buffers on February 27, 2024." +description = "Changes announced for Protobuf on February 27, 2024." type = "docs" +++ diff --git a/content/news/2024-06-26.md b/content/news/2024-06-26.md index 95a1606d6..59300675d 100644 --- a/content/news/2024-06-26.md +++ b/content/news/2024-06-26.md @@ -2,7 +2,7 @@ title = "Changes Announced on June 26, 2024" linkTitle = "June 26, 2024" toc_hide = "true" -description = "Changes announced for Protocol Buffers on June 26, 2024." +description = "Changes announced for Protobuf on June 26, 2024." type = "docs" +++ @@ -16,7 +16,7 @@ After this point, you can continue to use Bazel, or another build system, to build Protobuf. You can read more about building from source in [the Protobuf Java README](https://github.com/protocolbuffers/protobuf/tree/main/java). -This change may impact Protobuf Java contributors that build protobuf from +This change may impact Protobuf Java contributors that build Protobuf from source. It does not impact the majority of users that uses the precompiled protobuf-java or protobuf-javalite artifacts from a repository. Note specifically that we do not plan to stop supporting the ability to compile diff --git a/content/news/2024-10-01.md b/content/news/2024-10-01.md index 9a2ad57d9..d56ddfcd7 100644 --- a/content/news/2024-10-01.md +++ b/content/news/2024-10-01.md @@ -2,13 +2,13 @@ title = "Changes Announced on October 1, 2024" linkTitle = "October 1, 2024" toc_hide = "true" -description = "Changes announced for Protocol Buffers on October 1, 2024." +description = "Changes announced for Protobuf on October 1, 2024." type = "docs" +++ ## Bazel and Proto Rules -There are upcoming changes to the way that Bazel will work for protobuf builds. +There are upcoming changes to the way that Bazel will work for Protobuf builds. These changes require awareness in the first stage, and action by project owners before the second stage. @@ -16,12 +16,12 @@ before the second stage. With the release of Bazel 8, proto rules (`proto_library`, `cc_proto_library`, `java_proto_library`, `java_lite_proto_library`, and `py_proto_library`) will be -removed from the Bazel project. The will be added to the Protocol Buffers -project in v29. Bazel will be updated to automatically use the rules from the -protobuf project, so the change is initially a no-op for project owners. +removed from the Bazel project. They will be added to the Protobuf project in +v29. Bazel will be updated to automatically use the rules from the Protobuf +project, so the change is initially a no-op for project owners. After the release of Bazel 8 and before the release of Bazel 9, users will need -to explicitly `load` the rules from the Protocol Buffers project repository. The +to explicitly `load` the rules from the Protobuf project repository. The automatic use of the rules is only temporary to support the migration. Users should add the following `load()` statements to any `BUILD` or `.bzl` @@ -39,11 +39,11 @@ load("@protobuf//bazel:py_proto_library.bzl", "py_proto_library") ### Stage 2 -When Bazel 9 is released, the automatic loading of the protobuf library’s rules +When Bazel 9 is released, the automatic loading of the Protobuf library’s rules will be removed. At that point, you will need to have `load` statements in your Bazel build files. ### End Goal -Once the rules are in the protobuf repo, we intend to address common user +Once the rules are in the Protobuf repo, we intend to address common user requests, such as using prebuilts for the proto compiler where possible. diff --git a/content/news/2024-10-02.md b/content/news/2024-10-02.md index 45ddbe68e..4c62bbe33 100644 --- a/content/news/2024-10-02.md +++ b/content/news/2024-10-02.md @@ -2,7 +2,7 @@ title = "Changes Announced on October 2, 2024" linkTitle = "October 2, 2024" toc_hide = "true" -description = "Changes announced for Protocol Buffers on October 2, 2024." +description = "Changes announced for Protobuf on October 2, 2024." type = "docs" +++ diff --git a/content/news/2024-11-07.md b/content/news/2024-11-07.md index a41587005..008b57479 100644 --- a/content/news/2024-11-07.md +++ b/content/news/2024-11-07.md @@ -2,7 +2,7 @@ title = "Changes Announced on November 7, 2024" linkTitle = "November 7, 2024" toc_hide = "true" -description = "Changes announced for Protocol Buffers on November 7, 2024." +description = "Changes announced for Protobuf on November 7, 2024." type = "docs" +++ @@ -17,10 +17,10 @@ how they are described in this topic. ## Introduce ASAN Poisoning After Clearing Oneof Messages on Arena -This change adds a hardening check that affects C++ protobufs using Arenas. -Oneof messages allocated on the protobuf arena will now be cleared in debug and -poisoned in ASAN mode. After calling clear, future attempts to use the memory -region will cause a crash in ASAN as a use-after-free error. +This change adds a hardening check that affects C++ Protobuf messages using +Arenas. Oneof messages allocated on the Protobuf arena will now be cleared in +debug and poisoned in ASAN mode. After calling clear, future attempts to use the +memory region will cause a crash in ASAN as a use-after-free error. This implementation [requires C++17](/news/2024-10-02#drop-cpp-14). @@ -37,7 +37,7 @@ The deprecated internal `py_proto_library` Bazel macro in `protobuf.bzl` will be removed in v30.x. This should be replaced by the official `py_proto_library` which will be moved -to protobuf in `bazel/py_proto_library` as of v29.x. This implementation was +to Protobuf in `bazel/py_proto_library` as of v29.x. This implementation was previously available in `rules_python` prior to v29.x. ## Python Nested Message Class \_\_qualname\_\_ Contains the Outer Message Name diff --git a/content/news/2024-12-04.md b/content/news/2024-12-04.md index 927799b9e..6ce0f63b4 100644 --- a/content/news/2024-12-04.md +++ b/content/news/2024-12-04.md @@ -2,7 +2,7 @@ title = "Changes announced December 4, 2024" linkTitle = "December 4, 2024" toc_hide = "true" -description = "Changes announced for Protocol Buffers on December 4, 2024." +description = "Changes announced for Protobuf on December 4, 2024." type = "docs" +++ diff --git a/content/news/2024-12-13.md b/content/news/2024-12-13.md index d54dd2837..f91f60dee 100644 --- a/content/news/2024-12-13.md +++ b/content/news/2024-12-13.md @@ -2,7 +2,7 @@ title = "Changes announced December 13, 2024" linkTitle = "December 13, 2024" toc_hide = "true" -description = "Changes announced for Protocol Buffers on December 13, 2024." +description = "Changes announced for Protobuf on December 13, 2024." type = "docs" +++ diff --git a/content/news/2024-12-18.md b/content/news/2024-12-18.md index 3cb8db458..cd8821b5d 100644 --- a/content/news/2024-12-18.md +++ b/content/news/2024-12-18.md @@ -2,7 +2,7 @@ title = "Changes announced December 18, 2024" linkTitle = "December 18, 2024" toc_hide = "true" -description = "Changes announced for Protocol Buffers on December 18, 2024." +description = "Changes announced for Protobuf on December 18, 2024." type = "docs" +++ @@ -17,14 +17,14 @@ implementation and the [`protocmp`](https://pkg.go.dev/google.golang.org/protobuf/testing/protocmp) package for easier testing. -That release introduced a new protobuf module with a new API. Today, we are +That release introduced a new Protobuf module with a new API. Today, we are releasing an additional API for generated code, meaning the Go code in the `.pb.go` files created by the protocol compiler (`protoc`). The blog post at https://go.dev/blog/protobuf-opaque explains our motivation for creating a new API and shows you how to use it in your projects. To be clear: We are not removing anything. We will continue to support the -existing API for generated code, just like we still support the older protobuf +existing API for generated code, just like we still support the older Protobuf module (by wrapping the `google.golang.org/protobuf` implementation). Go is [committed to backwards compatibility](https://go.dev/blog/compat) and this applies to Go Protobuf, too! diff --git a/content/news/2025-01-23.md b/content/news/2025-01-23.md index fe42e3f63..a564f03eb 100644 --- a/content/news/2025-01-23.md +++ b/content/news/2025-01-23.md @@ -2,7 +2,7 @@ title = "Changes announced January 23, 2025" linkTitle = "January 23, 2025" toc_hide = "true" -description = "Changes announced for Protocol Buffers on January 23, 2025." +description = "Changes announced for Protobuf on January 23, 2025." type = "docs" +++ @@ -11,7 +11,7 @@ type = "docs" We are patching a change into the 25.x branch that will poison Java gencode that was created prior to the [3.21.7 release](https://github.com/protocolbuffers/protobuf/releases/tag/v21.7). -We will then mark all versions of Java protobuf from 3.21.7 through 3.25.5 as +We will then mark all versions of Java Protobuf from 3.21.7 through 3.25.5 as vulnerable to the [footmitten CVE](https://github.com/protocolbuffers/protobuf/security/advisories/GHSA-h4h5-3hr4-j3g2). @@ -34,7 +34,7 @@ opt-out flag `--define=protobuf_allow_msvc=true` to silence it.~~ ~~MSVC's path length limits combined with Bazel's sandboxing have become increasingly difficult to support in combination. Rather than randomly break -users who install protobuf into a long path, we will prohibit the use of MSVC +users who install Protobuf into a long path, we will prohibit the use of MSVC from Bazel altogether. We will continue to support MSVC with CMake, and begin supporting [clang-cl](https://clang.llvm.org/docs/UsersManual.html#clang-cl) with Bazel. For any feedback or discussion, see diff --git a/content/news/2025-03-18.md b/content/news/2025-03-18.md index fe810aa2b..a64c5319d 100644 --- a/content/news/2025-03-18.md +++ b/content/news/2025-03-18.md @@ -2,7 +2,7 @@ title = "Changes Announced on March 18, 2025" linkTitle = "March 18, 2025" toc_hide = "true" -description = "Changes announced for Protocol Buffers on March 18, 2025." +description = "Changes announced for Protobuf on March 18, 2025." type = "docs" +++ diff --git a/content/news/2025-06-27.md b/content/news/2025-06-27.md index 333f0cb13..9503aa7b5 100644 --- a/content/news/2025-06-27.md +++ b/content/news/2025-06-27.md @@ -2,7 +2,7 @@ title = "Changes Announced on June 27, 2025" linkTitle = "June 27, 2025" toc_hide = "true" -description = "Changes announced for Protocol Buffers on June 27, 2025." +description = "Changes announced for Protobuf on June 27, 2025." type = "docs" +++ @@ -169,7 +169,7 @@ proto_library( ``` Option imports and `option_deps` are strongly recommended when importing -protobuf language features and other custom options to avoid generating +Protobuf language features and other custom options to avoid generating unnecessary code. `option_deps` requires Bazel 8 or later since the `native.proto_library` in diff --git a/content/news/2025-07-14.md b/content/news/2025-07-14.md index 95baca143..af84223da 100644 --- a/content/news/2025-07-14.md +++ b/content/news/2025-07-14.md @@ -2,7 +2,7 @@ title = "Changes Announced on July 14, 2025" linkTitle = "July 14, 2025" toc_hide = "true" -description = "Changes announced for Protocol Buffers on July 14, 2025." +description = "Changes announced for Protobuf on July 14, 2025." type = "docs" +++ @@ -15,8 +15,8 @@ being deprecated as we encourage the use of more precise accessor methods. ### Background While at one time the `FieldDescriptor.label` enum served a purpose, the -evolution of Protocol Buffers has introduced more idiomatic ways to determine a -field's cardinality (singular/repeated) and presence semantics. +evolution of Protobuf has introduced more idiomatic ways to determine a field's +cardinality (singular/repeated) and presence semantics. * In proto2, `optional`, `required`, and `repeated` are explicit keywords. * In proto3, `required` is no longer supported. All scalar fields are @@ -38,7 +38,7 @@ The `FieldDescriptor.label` field will eventually be removed from the API. Note that the method names in this topic may be spelled slightly differently in some languages. -* **For Protocol Buffer Editions fields:** +* **For Protobuf Editions fields:** * **Key Methods for Editions:** * `hasPresence` becomes the primary method to determine if a singular field tracks presence, reflecting the @@ -50,9 +50,9 @@ some languages. * **For proto2/proto3 fields:** `getLabel` will eventually be removed, and is not recommended in the meantime. -All users of Protocol Buffers who interact with `FieldDescriptor` objects in -their code (for example for code generation, reflection, and dynamic message -handling) should migrate away from using `FieldDescriptor.label` directly. +All users of Protobuf who interact with `FieldDescriptor` objects in their code +(for example for code generation, reflection, and dynamic message handling) +should migrate away from using `FieldDescriptor.label` directly. Instead, update your code to use the following methods: @@ -66,4 +66,4 @@ Instead, update your code to use the following methods: This deprecation is effective immediately. While `getLabel` will continue to function, we recommend migrating your code proactively to ensure future compatibility and clarity. This change will lead to a more robust and -understandable experience for developers using Protocol Buffers. +understandable experience for developers using Protobuf. diff --git a/content/news/2025-07-16.md b/content/news/2025-07-16.md index 9222ebeff..4edfda570 100644 --- a/content/news/2025-07-16.md +++ b/content/news/2025-07-16.md @@ -2,7 +2,7 @@ title = "Changes Announced on July 16, 2025" linkTitle = "July 16, 2025" toc_hide = "true" -description = "Changes announced for Protocol Buffers on July 16, 2025." +description = "Changes announced for Protobuf on July 16, 2025." type = "docs" +++ diff --git a/content/news/2025-09-19.md b/content/news/2025-09-19.md index 777505afb..b3fe33c4d 100644 --- a/content/news/2025-09-19.md +++ b/content/news/2025-09-19.md @@ -2,7 +2,7 @@ title = "Changes Announced on September 19, 2025" linkTitle = "September 19, 2025" toc_hide = "true" -description = "Changes announced for Protocol Buffers on September 19, 2025." +description = "Changes announced for Protobuf on September 19, 2025." type = "docs" +++ @@ -39,7 +39,7 @@ arena-safe counterparts and be deprecated. ### MSB Hardening Check on RepeatedField::Get and RepeatedPtrField::Get {#cpp-repeatedfield-get-hardening} -Protobufs will be hardened against OOB errors by adding comprehensive bounds +Protobuf will be hardened against OOB errors by adding comprehensive bounds checking to repeated field accesses. @@ -96,7 +96,7 @@ This release will remove the macro. ### Stricter Name Length Limits {#cpp-name-limits} -The protobuf compiler will enforce stricter limits on the length of symbol +The Protobuf compiler will enforce stricter limits on the length of symbol names, such as field names, to prevent potential issues. If the length of any field name is > 2^16, it will generate an error. @@ -107,7 +107,7 @@ not affect most users. ### [[nodiscard]] on Logically Constant Operations {#cpp-nodiscard} -`[[nodiscard]]` will be added to several logically constant protobuf APIs where +`[[nodiscard]]` will be added to several logically constant Protobuf APIs where failure to consume the returned value indicates a probable bug. This follows patterns used commonly in the C++ standard library. diff --git a/content/news/2026-01-16.md b/content/news/2026-01-16.md index 4e70d2fa8..ac74397be 100644 --- a/content/news/2026-01-16.md +++ b/content/news/2026-01-16.md @@ -2,24 +2,24 @@ title = "Changes Announced on January 16, 2026" linkTitle = "January 16, 2026" toc_hide = "true" -description = "Changes announced for Protocol Buffers on January 16, 2026." +description = "Changes announced for Protobuf on January 16, 2026." type = "docs" +++ ## Prebuilt proto compiler (protoc) for Bazel -In an effort to speed up builds, protobuf 33.4 offers an option to skip +In an effort to speed up builds, Protobuf 33.4 offers an option to skip re-compiling Protobuf tools and runtimes and use a pre-built protoc binary, available to Bazel 7 and later. Using a pre-built protoc also avoids build failures from incompatible or non-hermetic C++ compilation toolchain installed on your machine. -To use the prebuilt protoc, upgrade to protobuf version 33.4 or later, and set +To use the prebuilt protoc, upgrade to Protobuf version 33.4 or later, and set the `--incompatible_enable_proto_toolchain_resolution` and `--@protobuf//bazel/flags:prefer_prebuilt_protoc` flags. The first flag is set by default in Bazel 9 onwards. -In the breaking v34 release, protobuf will change the default of +In the breaking v34 release, Protobuf will change the default of `--@protobuf//bazel/flags:prefer_prebuilt_protoc` to true. ### Reasons not to use the prebuilt compiler @@ -39,5 +39,5 @@ For information on troubleshooting the prebuilt protoc compiler configuration, see [Bazel: Resolving Issues with Prebuilt Protoc](/support/debugging-playbook#prebuilt-protoc) -For more information on other changes in Bazel 9 that affect Protocol Buffers, -see https://bazel.build/about/roadmap. +For more information on other changes in Bazel 9 that affect Protobuf, see +https://bazel.build/about/roadmap. diff --git a/content/news/2026-03-13.md b/content/news/2026-03-13.md index 47cd10571..51b226677 100644 --- a/content/news/2026-03-13.md +++ b/content/news/2026-03-13.md @@ -2,7 +2,7 @@ title = "Changes Announced on March 13, 2026" linkTitle = "March 13, 2026" toc_hide = "true" -description = "Changes announced for Protocol Buffers on March 13, 2026." +description = "Changes announced for Protobuf on March 13, 2026." type = "docs" +++ diff --git a/content/news/2026-05-18.md b/content/news/2026-05-18.md index a3688b3fa..b3017c778 100644 --- a/content/news/2026-05-18.md +++ b/content/news/2026-05-18.md @@ -2,7 +2,7 @@ title = "Changes Announced on May 18, 2026" linkTitle = "March 18, 2026" toc_hide = "true" -description = "Changes announced for Protocol Buffers on March 18, 2026." +description = "Changes announced for Protobuf on March 18, 2026." type = "docs" +++ diff --git a/content/news/2026-06-16.md b/content/news/2026-06-16.md index c39f0e190..02f44317a 100644 --- a/content/news/2026-06-16.md +++ b/content/news/2026-06-16.md @@ -2,7 +2,7 @@ title = "Changes Announced on June 16, 2026" linkTitle = "June 16, 2026" toc_hide = "true" -description = "Changes announced for Protocol Buffers on June 16, 2026." +description = "Changes announced for Protobuf on June 16, 2026." type = "docs" +++ diff --git a/content/news/2026-07-13.md b/content/news/2026-07-13.md index 72c3a7bf3..4506102f8 100644 --- a/content/news/2026-07-13.md +++ b/content/news/2026-07-13.md @@ -2,7 +2,7 @@ title = "Changes Announced on July 13, 2026" linkTitle = "July 13, 2026" toc_hide = "true" -description = "Changes announced for Protocol Buffers on July 13, 2026." +description = "Changes announced for Protobuf on July 13, 2026." type = "docs" +++ diff --git a/content/news/2026-09-22.md b/content/news/2026-09-22.md index 125ae4aba..a29234297 100644 --- a/content/news/2026-09-22.md +++ b/content/news/2026-09-22.md @@ -2,7 +2,7 @@ title = "Changes Announced on September 22, 2026" linkTitle = "September 22, 2026" toc_hide = "true" -description = "Changes announced for Protocol Buffers on September 22, 2026." +description = "Changes announced for Protobuf on September 22, 2026." type = "docs" +++ @@ -74,7 +74,7 @@ C++ will bump its major version from 7.37.x to 8.38.x. ### Add `[[nodiscard]]` Remove the `PROTOBUF_FUTURE_ADD_NODISCARD` macro. `[[nodiscard]]` was previously -introduced to several protobuf APIs to produce compile-time warnings for common +introduced to several Protobuf APIs to produce compile-time warnings for common API misuses and avoid footguns. This change removes the temporary transition flag macro, making the `[[nodiscard]]` annotations permanent. @@ -124,7 +124,7 @@ eliminates the risk of naming collisions, which can cause breakages. Mark several message implementation fields as transient so that they do not serialize in formats that respect the transient tag – particularly GSON. Do not -use GSON on generated protobuf classes without one of the protobuf type adapters +use GSON on generated Protobuf classes without one of the Protobuf type adapters distributed with GSON. ### UTF-8 Validation Feature @@ -165,7 +165,7 @@ message. Attempting to modify the returned options object raises ### Return `NotImplemented` for Unrecognized Types When comparing equality against unrecognized types, the C++ and upb Python -protobuf implementations previously returned `False` directly. They now return +Protobuf implementations previously returned `False` directly. They now return `NotImplemented` to follow standard Python comparison behavior and allow reflected comparisons on the other operand. @@ -187,7 +187,7 @@ Enable piping down NX and ASLR security feature flags to target repository ### Parsing JSON Booleans Fix bug that allowed Python’s JSON parser to parse a boolean JSON into a -protobuf field of type int or float/double. +Protobuf field of type int or float/double. ### Generic Services Option @@ -217,8 +217,8 @@ Enforce UTF-8 validity in the upb json decoder. ## Conformance Tests {#conformance-tests} -The Protocol Buffers project maintains an extensive conformance test suite to -ensure consistent behavior across languages and runtimes. As part of our ongoing +The Protobuf project maintains an extensive conformance test suite to ensure +consistent behavior across languages and runtimes. As part of our ongoing commitment to specification compliance and interoperability, we are actively working to address and implement a number of conformance test updates. diff --git a/content/news/_index.md b/content/news/_index.md index 77472658c..52059fe32 100644 --- a/content/news/_index.md +++ b/content/news/_index.md @@ -1,15 +1,15 @@ +++ title = "News" weight = 20 -description = "Get the latest news about Protocol Buffers." +description = "Get the latest news about Protobuf." type = "docs" no_list = "true" +++ -News topics provide information about past events and changes with Protocol -Buffers, and plans for upcoming changes. The information is available both -chronologically and per-release. Note that not everything is included in the -per-release topics, as some content is not tied to a version. +News topics provide information about past events and changes with Protobuf, and +plans for upcoming changes. The information is available both chronologically +and per-release. Note that not everything is included in the per-release topics, +as some content is not tied to a version. New news topics will also be published to the [protobuf@](https://groups.google.com/g/protobuf) mailing list under the subject diff --git a/content/news/v21.md b/content/news/v21.md index 4634ec40f..8fc2aa4ff 100644 --- a/content/news/v21.md +++ b/content/news/v21.md @@ -2,7 +2,7 @@ title = "News Announcements for Version 21.x" linkTitle = "Version 21.x" toc_hide = "true" -description = "Changes announced for Protocol Buffers version 21.x." +description = "Changes announced for Protobuf version 21.x." type = "docs" +++ @@ -12,8 +12,8 @@ The following announcements are specific to Version 21.x, which was released May ## Python Updates {#python-updates} -We made some changes in Python language support in Protocol Buffers. Version -4.21.0 is a new major version, following 3.20.1. The new version is based on the +We made some changes in Python language support in Protobuf. Version 4.21.0 is a +new major version, following 3.20.1. The new version is based on the [upb library](https://github.com/protocolbuffers/upb), and offers significantly better parsing performance than previous releases, especially for large payloads. It also includes prebuilt binary modules for Apple silicon for diff --git a/content/news/v22.md b/content/news/v22.md index 23b1fdca4..16d778ad3 100644 --- a/content/news/v22.md +++ b/content/news/v22.md @@ -2,7 +2,7 @@ title = "News Announcements for Version 22.x" linkTitle = "Version 22.x" toc_hide = "true" -description = "Changes announced for Protocol Buffers version 22.x." +description = "Changes announced for Protobuf version 22.x." type = "docs" +++ @@ -17,7 +17,7 @@ release candidate prefix. ### Adding an Abseil Dependency {#abseil-dep} -In order to reduce the Google vs. OSS differences between protobuf and to +In order to reduce the Google vs. OSS differences between Protobuf and to simplify our own project, we plan to take a formal dependency on Abseil. In time, we plan to start using Abseil types in our public APIs, but simply adding the dependency is a breaking change. @@ -34,7 +34,7 @@ breaking change since these versions are already EOL in the broader ecosystem. Per our [build systems support policy](https://opensource.google/documentation/policies/cplusplus-support#3_build_systems), we plan to drop autotools support. This is a breaking change. After autotools -support is dropped, protobuf will support only CMake and Bazel. +support is dropped, Protobuf will support only CMake and Bazel. ### Dropping C++11 Support {#c11-support} @@ -58,6 +58,6 @@ we are planning a major version bump for C++. We plan to make some changes to the assets that we release starting with our 22.x release line. The following sections outline the set of breaking changes that we plan to -include in the 22.0 release of protocol buffers. Note that plans can and do -change. These are potential breaking changes to be aware of, but they may not -happen in this particular release, or they may not happen at all. +include in the 22.0 release of Protobuf. Note that plans can and do change. +These are potential breaking changes to be aware of, but they may not happen in +this particular release, or they may not happen at all. diff --git a/content/news/v23.md b/content/news/v23.md index c33eb9026..3e9cef39f 100644 --- a/content/news/v23.md +++ b/content/news/v23.md @@ -2,7 +2,7 @@ title = "News Announcements for Version 23.x" linkTitle = "Version 23.x" toc_hide = "true" -description = "Changes announced for Protocol Buffers version 23.x." +description = "Changes announced for Protobuf version 23.x." type = "docs" +++ diff --git a/content/news/v24.md b/content/news/v24.md index 4fd1b15fb..6fee7805a 100644 --- a/content/news/v24.md +++ b/content/news/v24.md @@ -2,7 +2,7 @@ title = "News Announcements for Version 24.x" linkTitle = "Version 24.x" toc_hide = "true" -description = "Changes announced for Protocol Buffers version 24.x." +description = "Changes announced for Protobuf version 24.x." type = "docs" +++ diff --git a/content/news/v25.md b/content/news/v25.md index 30d57201a..cf5f21bab 100644 --- a/content/news/v25.md +++ b/content/news/v25.md @@ -2,7 +2,7 @@ title = "News Announcements for Version 25.x" linkTitle = "Version 25.x" toc_hide = "true" -description = "Changes announced for Protocol Buffers version 25.x." +description = "Changes announced for Protobuf version 25.x." type = "docs" +++ @@ -22,14 +22,14 @@ support in `unknown_fields.py` as a replacement. ## μpb Moving to the Protobuf Git Repository Starting with the v25 release, μpb now lives in the -[protobuf repo](https://github.com/protocolbuffers/protobuf) instead +[Protobuf repo](https://github.com/protocolbuffers/protobuf) instead of in its [former location](https://github.com/protocolbuffers/upb) in a separate repo. All μpb development going forward will take place only in the new location. The merger of the two repos will simplify and speed up our development process -by removing the need to update pinned version dependencies between protobuf and -μpb. Changes to μpb now take effect immediately in protobuf code and vice versa, +by removing the need to update pinned version dependencies between Protobuf and +μpb. Changes to μpb now take effect immediately in Protobuf code and vice versa, without the need for a manual upgrade step. We expect that most users will not need to take much, if any, action to @@ -38,7 +38,7 @@ implementations, but you will most likely not notice the change unless you have code that refers to μpb directly. If you refer to μpb from a Bazel project, you will need to update μpb references -to point to protobuf instead (for example, replace `@upb` with +to point to Protobuf instead (for example, replace `@upb` with `@com_google_protobuf`). We are keeping μpb file paths and Bazel targets the same to minimize the need for additional changes, but there are two exceptions: @@ -52,7 +52,7 @@ same to minimize the need for additional changes, but there are two exceptions: We are patching a change into the 25.x branch that will poison Java gencode that was created prior to the [3.21.7 release](https://github.com/protocolbuffers/protobuf/releases/tag/v21.7). -We will then mark all versions of Java protobuf from 3.21.7 through 3.25.5 as +We will then mark all versions of Java Protobuf from 3.21.7 through 3.25.5 as vulnerable to the [footmitten CVE](https://github.com/protocolbuffers/protobuf/security/advisories/GHSA-h4h5-3hr4-j3g2). diff --git a/content/news/v26.md b/content/news/v26.md index 8c5697218..ce67fc673 100644 --- a/content/news/v26.md +++ b/content/news/v26.md @@ -2,7 +2,7 @@ title = "News Announcements for Version 26.x" linkTitle = "Version 26.x" toc_hide = "true" -description = "Changes announced for Protocol Buffers version 26.x." +description = "Changes announced for Protobuf version 26.x." type = "docs" +++ @@ -48,9 +48,9 @@ In v26, we are planning a major version bump for C++ as per our [version support policy](/support/version-support#cpp-tooling). The following sections outline the set of breaking changes that we plan to -include in the 26.0 release of protocol buffers. Note that plans can and do -change. These are potential breaking changes to be aware of, but they may not -happen in this particular release, or they may not happen at all. +include in the 26.0 release of Protobuf. Note that plans can and do change. +These are potential breaking changes to be aware of, but they may not happen in +this particular release, or they may not happen at all. ### Remove deprecated clear APIs on repeated fields @@ -93,9 +93,9 @@ In v26, we are planning a major version bump for Java per our [version support policy](/support/version-support#java). The following sections outline the set of breaking changes that we plan to -include in the 26.0 release of protocol buffers. Note that plans can and do -change. These are potential breaking changes to be aware of, but they may not -happen in this particular release, or they may not happen at all. +include in the 26.0 release of Protobuf. Note that plans can and do change. +These are potential breaking changes to be aware of, but they may not happen in +this particular release, or they may not happen at all. ### Breaking Compatibility with Old Generated Code diff --git a/content/news/v29.md b/content/news/v29.md index a4bfe9bec..5107b7721 100644 --- a/content/news/v29.md +++ b/content/news/v29.md @@ -2,7 +2,7 @@ title = "News Announcements for Version 29.x" linkTitle = "Version 29.x" toc_hide = "true" -description = "Changes announced for Protocol Buffers version 29.x." +description = "Changes announced for Protobuf version 29.x." type = "docs" +++ @@ -12,7 +12,7 @@ November 27, 2024. For information presented chronologically, see ## Bazel and Proto Rules -There are upcoming changes to the way that Bazel will work for protobuf builds. +There are upcoming changes to the way that Bazel will work for Protobuf builds. These changes require awareness in the first stage, and action by project owners before the second stage. @@ -20,12 +20,12 @@ before the second stage. With the release of Bazel 8, proto rules (`proto_library`, `cc_proto_library`, `java_proto_library`, `java_lite_proto_library`, and `py_proto_library`) will be -removed from the Bazel project. The will be added to the Protocol Buffers -project in v29. Bazel will be updated to automatically use the rules from the -protobuf project, so the change is initially a no-op for project owners. +removed from the Bazel project. They will be added to the Protobuf project in +v29. Bazel will be updated to automatically use the rules from the Protobuf +project, so the change is initially a no-op for project owners. After the release of Bazel 8 and before the release of Bazel 9, users will need -to explicitly `load` the rules from the Protocol Buffers project repository. The +to explicitly `load` the rules from the Protobuf project repository. The automatic use of the rules is only temporary to support the migration. Users should add the following `load()` statements to any `BUILD` or `.bzl` @@ -43,11 +43,11 @@ load("@protobuf//bazel:py_proto_library.bzl", "py_proto_library") ### Stage 2 -When Bazel 9 is released, the automatic loading of the protobuf library’s rules +When Bazel 9 is released, the automatic loading of the Protobuf library’s rules will be removed. At that point, you will need to have `load` statements in your Bazel build files. ### End Goal -Once the rules are in the protobuf repo, we intend to address common user +Once the rules are in the Protobuf repo, we intend to address common user requests, such as using prebuilts for the proto compiler where possible. diff --git a/content/news/v30.md b/content/news/v30.md index b3b0871f3..8c764d6af 100644 --- a/content/news/v30.md +++ b/content/news/v30.md @@ -2,7 +2,7 @@ title = "News Announcements for Version 30.x" linkTitle = "Version 30.x" toc_hide = "true" -description = "Changes announced for Protocol Buffers version 30.x." +description = "Changes announced for Protobuf version 30.x." type = "docs" +++ @@ -114,10 +114,10 @@ consider this to be a breaking change. ### Introduce ASAN Poisoning After Clearing Oneof Messages on Arena -This change adds a hardening check that affects C++ protobufs using Arenas. -Oneof messages allocated on the protobuf arena will now be cleared in debug and -poisoned in ASAN mode. After calling clear, future attempts to use the memory -region will cause a crash in ASAN as a use-after-free error. +This change adds a hardening check that affects C++ Protobuf messages using +Arenas. Oneof messages allocated on the Protobuf arena will now be cleared in +debug and poisoned in ASAN mode. After calling clear, future attempts to use the +memory region will cause a crash in ASAN as a use-after-free error. This implementation requires C++17. @@ -167,7 +167,7 @@ The deprecated internal `py_proto_library` Bazel macro in `protobuf.bzl` will be removed in v30.x. This should be replaced by the official `py_proto_library` which will be moved -to protobuf in `bazel/py_proto_library` as of v29.x. This implementation was +to Protobuf in `bazel/py_proto_library` as of v29.x. This implementation was previously available in `rules_python` prior to v29.x. ### Remove Deprecated APIs {#python-remove-apis} @@ -392,7 +392,7 @@ flag `--define=protobuf_allow_msvc=true` to silence it. MSVC's path length limits combined with Bazel's sandboxing have become increasingly difficult to support in combination. Rather than randomly break -users who install protobuf into a long path, we will prohibit the use of MSVC +users who install Protobuf into a long path, we will prohibit the use of MSVC from Bazel altogether. We will continue to support MSVC with CMake, and begin supporting [clang-cl](https://clang.llvm.org/docs/UsersManual.html#clang-cl) with Bazel. For any feedback or discussion, see diff --git a/content/news/v31.md b/content/news/v31.md index 781ffbb88..1555c3f05 100644 --- a/content/news/v31.md +++ b/content/news/v31.md @@ -2,7 +2,7 @@ title = "News Announcements for Version 31.x" linkTitle = "Version 31.x" toc_hide = "true" -description = "Changes announced for Protocol Buffers version 31.x." +description = "Changes announced for Protobuf version 31.x." type = "docs" +++ @@ -33,8 +33,8 @@ are being deprecated as we encourage the use of more precise accessor methods. ### Background While at one time the `FieldDescriptor.label` enum served a purpose, the -evolution of Protocol Buffers has introduced more explicit ways to determine a -field's cardinality (singular/repeated) and presence semantics. +evolution of Protobuf has introduced more explicit ways to determine a field's +cardinality (singular/repeated) and presence semantics. * In proto2, `optional`, `required`, and `repeated` are explicit keywords. * In proto3, `required` is no longer supported. All scalar fields are @@ -55,7 +55,7 @@ The `FieldDescriptor.label` field will eventually be removed from the API to maintain backward compatibility. Note that the method names in this topic may be spelled slightly differently in some languages. -* **For Protocol Buffer Editions fields:** +* **For Protobuf Editions fields:** * **Behavior:** The `getLabel` method will be simplified: * It will return `FieldDescriptor.LABEL_OPTIONAL` for all singular fields. @@ -78,9 +78,9 @@ spelled slightly differently in some languages. `LABEL_REQUIRED`, or `LABEL_REPEATED` as defined in the .proto file for the time being. -All users of Protocol Buffers who interact with `FieldDescriptor` objects in -their code (for example for code generation, reflection, and dynamic message -handling) should migrate away from using `FieldDescriptor.label` directly. +All users of Protobuf who interact with `FieldDescriptor` objects in their code +(for example for code generation, reflection, and dynamic message handling) +should migrate away from using `FieldDescriptor.label` directly. Instead, update your code to use the following methods: @@ -96,4 +96,4 @@ Instead, update your code to use the following methods: This deprecation is effective immediately. While `getLabel` will continue to function, we recommend migrating your code proactively to ensure future compatibility and clarity. This change will lead to a more robust and -understandable experience for developers using Protocol Buffers. +understandable experience for developers using Protobuf. diff --git a/content/news/v32.md b/content/news/v32.md index d78dbe2a6..f7a355af6 100644 --- a/content/news/v32.md +++ b/content/news/v32.md @@ -2,7 +2,7 @@ title = "News Announcements for Version 32.x" linkTitle = "Version 32.x" toc_hide = "true" -description = "Changes announced for Protocol Buffers version 32.x." +description = "Changes announced for Protobuf version 32.x." type = "docs" +++ @@ -157,7 +157,7 @@ proto_library( ``` Option imports and `option_deps` are strongly recommended when importing -protobuf language features and other custom options to avoid generating +Protobuf language features and other custom options to avoid generating unnecessary code. `option_deps` requires Bazel 8 or later since the `native.proto_library` in diff --git a/content/news/v34.md b/content/news/v34.md index 1d9d4d05f..9b0d8fd61 100644 --- a/content/news/v34.md +++ b/content/news/v34.md @@ -2,7 +2,7 @@ title = "News Announcements for Version 34.x" linkTitle = "Version 34.x" toc_hide = "true" -description = "Changes announced for Protocol Buffers version 34.x." +description = "Changes announced for Protobuf version 34.x." type = "docs" +++ diff --git a/content/overview.md b/content/overview.md index eb82279b6..6af975630 100644 --- a/content/overview.md +++ b/content/overview.md @@ -1,34 +1,34 @@ +++ title = "Overview" weight = 10 -description = "Protocol Buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data." +description = "Protobuf is a language-neutral, platform-neutral extensible mechanism for serializing structured data." type = "docs" +++ -It’s like JSON, except it's -smaller and faster, and it generates native language bindings. 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. +It’s like JSON, except it's smaller and faster, and it +generates native language bindings. 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. -Protocol buffers are a combination of the definition language (created in -`.proto` files), the code that the proto compiler generates to interface with -data, language-specific runtime libraries, the serialization format for data -that is written to a file (or sent across a network connection), and the -serialized data. +Protobuf is a combination of the definition language (created in `.proto` +files), the code that the proto compiler generates to interface with data, +language-specific runtime libraries, the serialization format for data that is +written to a file (or sent across a network connection), and the serialized +data. -## What Problems do Protocol Buffers Solve? {#solve} +## What Problems Does Protobuf Solve? {#solve} -Protocol buffers provide a serialization format for packets of typed, structured -data that are up to a few megabytes in size. The format is suitable for both -ephemeral network traffic and long-term data storage. Protocol buffers can be -extended with new information without invalidating existing data or requiring -code to be updated. +Protobuf provides a serialization format for packets of typed, structured data +that are up to a few megabytes in size. The format is suitable for both +ephemeral network traffic and long-term data storage. Protobuf can be extended +with new information without invalidating existing data or requiring code to be +updated. -Protocol buffers are the most commonly-used data format at Google. They are used -extensively in inter-server communications as well as for archival storage of -data on disk. Protocol buffer *messages* and *services* are described by -engineer-authored `.proto` files. The following shows an example `message`: +Protobuf is the most commonly-used data format at Google. It is used extensively +in inter-server communications as well as for archival storage of data on disk. +Protobuf *messages* and *services* are described by engineer-authored `.proto` +files. The following shows an example `message`: ```proto edition = "2023"; @@ -43,7 +43,7 @@ message Person { The proto compiler is invoked at build time on `.proto` files to generate code in various programming languages (covered in [Cross-language Compatibility](#cross-lang) later in this topic) to manipulate -the corresponding protocol buffer. Each generated class contains simple +the corresponding Protobuf message. Each generated class contains simple accessors for each field and methods to serialize and parse the whole structure to and from raw bytes. The following shows you an example that uses those generated methods: @@ -58,23 +58,22 @@ output = new FileOutputStream(args[0]); john.writeTo(output); ``` -Because protocol buffers are used extensively across all manner of services at -Google and data within them may persist for some time, maintaining backwards -compatibility is crucial. Protocol buffers allow for the seamless support of -changes, including the addition of new fields and the deletion of existing -fields, to any protocol buffer without breaking existing services. For more on -this topic, see +Because Protobuf is used extensively across all manner of services at Google and +data within messages may persist for some time, maintaining backwards +compatibility is crucial. Protobuf allows for the seamless support of changes, +including the addition of new fields and the deletion of existing fields, to any +Protobuf message without breaking existing services. For more on this topic, see [Updating Proto Definitions Without Updating Code](#updating-defs), later in this topic. -## What are the Benefits of Using Protocol Buffers? {#benefits} +## What Are the Benefits of Using Protobuf? {#benefits} -Protocol buffers are ideal for any situation in which you need to serialize -structured, record-like, typed data in a language-neutral, platform-neutral, -extensible manner. They are most often used for defining communications -protocols (together with gRPC) and for data storage. +Protobuf is ideal for any situation in which you need to serialize structured, +record-like, typed data in a language-neutral, platform-neutral, extensible +manner. It is most often used for defining communications protocols (together +with gRPC) and for data storage. -Some of the advantages of using protocol buffers include: +Some of the advantages of using Protobuf include: * Compact data storage * Fast parsing @@ -89,8 +88,7 @@ software system, serialize it based on a `.proto` definition, and then extract specific values from that serialized data in a separate Python application running on another platform. -The following languages are supported directly in the protocol buffers compiler, -protoc: +The following languages are supported directly in the Protobuf compiler, protoc: * [C++](/reference/cpp/cpp-generated#invocation) * [C#](/reference/csharp/csharp-generated#invocation) @@ -110,15 +108,14 @@ languages: Additional languages are not directly supported by Google, but rather by other GitHub projects. These languages are covered in -[Third-Party Add-ons for Protocol Buffers](https://github.com/protocolbuffers/protobuf/blob/master/docs/third_party.md). +[Third-Party Add-ons for Protobuf](https://github.com/protocolbuffers/protobuf/blob/master/docs/third_party.md). ### Cross-project Support {#cross-proj} -You can use protocol buffers across projects by defining `message` types in -`.proto` files that reside outside of a specific project’s code base. If you're -defining `message` types or enums that you anticipate will be widely used -outside of your immediate team, you can put them in their own file with no -dependencies. +You can use Protobuf across projects by defining `message` types in `.proto` +files that reside outside of a specific project’s code base. If you're defining +`message` types or enums that you anticipate will be widely used outside of your +immediate team, you can put them in their own file with no dependencies. A couple of examples of proto definitions widely-used within Google are [`timestamp.proto`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/timestamp.proto) @@ -134,60 +131,60 @@ when updating `.proto` definitions, old code will read new messages without issues, ignoring any newly added fields. To the old code, fields that were deleted will have their default value, and deleted repeated fields will be empty. For information on what “repeated” fields are, see -[Protocol Buffers Definition Syntax](#syntax) later in this topic. +[Protobuf Definition Syntax](#syntax) later in this topic. New code will also transparently read old messages. New fields will not be -present in old messages; in these cases protocol buffers provide a reasonable -default value. +present in old messages; in these cases Protobuf provides a reasonable default +value. -### When are Protocol Buffers not a Good Fit? {#not-good-fit} +### When Is Protobuf Not a Good Fit? {#not-good-fit} -Protocol buffers do not fit all data. In particular: +Protobuf does not fit all data. In particular: -* Protocol buffers tend to assume that entire messages can be loaded into - memory at once and are not larger than an object graph. For data that - exceeds a few megabytes, consider a different solution; when working with - larger data, you may effectively end up with several copies of the data due - to serialized copies, which can cause surprising spikes in memory usage. -* When protocol buffers are serialized, the same data can have many different +* Protobuf tends to assume that entire messages can be loaded into memory at + once and are not larger than an object graph. For data that exceeds a few + megabytes, consider a different solution; when working with larger data, you + may effectively end up with several copies of the data due to serialized + copies, which can cause surprising spikes in memory usage. +* When Protobuf messages are serialized, the same data can have many different binary serializations. You cannot compare two messages for equality without fully parsing them. * Messages are not compressed. While messages can be zipped or gzipped like any other file, special-purpose compression algorithms like the ones used by JPEG and PNG will produce much smaller files for data of the appropriate type. -* Protocol buffer messages are less than maximally efficient in both size and - speed for many scientific and engineering uses that involve large, +* Protobuf messages are less than maximally efficient in both size and speed + for many scientific and engineering uses that involve large, multi-dimensional arrays of floating point numbers. For these applications, [FITS](https://en.wikipedia.org/wiki/FITS) and similar formats have less overhead. -* Protocol buffers are not well supported in non-object-oriented languages - popular in scientific computing, such as Fortran and IDL. -* Protocol buffer messages don't inherently self-describe their data, but they - have a fully reflective schema that you can use to implement - self-description. That is, you cannot fully interpret one without access to - its corresponding `.proto` file. -* Protocol buffers are not a formal standard of any organization. This makes - them unsuitable for use in environments with legal or other requirements to - build on top of standards. +* Protobuf is not well supported in non-object-oriented languages popular in + scientific computing, such as Fortran and IDL. +* Protobuf messages don't inherently self-describe their data, but they have a + fully reflective schema that you can use to implement self-description. That + is, you cannot fully interpret one without access to its corresponding + `.proto` file. +* Protobuf is not a formal standard of any organization. This makes it + unsuitable for use in environments with legal or other requirements to build + on top of standards. -## Who Uses Protocol Buffers? {#who-uses} +## Who Uses Protobuf? {#who-uses} -Many projects use protocol buffers, including the following: +Many projects use Protobuf, including the following: + [gRPC](https://grpc.io) + [Google Cloud](https://cloud.google.com) + [Envoy Proxy](https://www.envoyproxy.io) -## How do Protocol Buffers Work? {#work} +## How Does Protobuf Work? {#work} -The following diagram shows how you use protocol buffers to work with your data. +The following diagram shows how you use Protobuf to work with your data. ![Compilation workflow showing the creation of a proto file, generated code, and compiled classes](/images/protocol-buffers-concepts.png) \ -**Figure 1. Protocol buffers workflow** +**Figure 1. Protobuf workflow** -The code generated by protocol buffers provides utility methods to retrieve data -from files and streams, extract individual values from the data, check if data +The code generated by Protobuf provides utility methods to retrieve data from +files and streams, extract individual values from the data, check if data exists, serialize data back to a file or stream, and other useful functions. The following code samples show you an example of this flow in Java. As shown @@ -214,8 +211,8 @@ output = new FileOutputStream(args[0]); john.writeTo(output); ``` -You can then deserialize data using the methods protocol buffers creates in -other languages, like C++: +You can then deserialize data using the methods Protobuf creates in other +languages, like C++: ```cpp Person john; @@ -226,16 +223,16 @@ std::string name = john.name(); std::string email = john.email(); ``` -## Protocol Buffers Definition Syntax {#syntax} +## Protobuf Definition Syntax {#syntax} When defining `.proto` files, you can specify cardinality (singular or repeated). In proto2 and proto3, you can also specify if the field is optional. In proto3, setting a field to optional [changes it from implicit presence to explicit presence](/programming-guides/field_presence). -After setting the cardinality of a field, you specify the data type. Protocol -buffers support the usual primitive data types, such as integers, booleans, and -floats. For the full list, see +After setting the cardinality of a field, you specify the data type. Protobuf +supports the usual primitive data types, such as integers, booleans, and floats. +For the full list, see [Scalar Value Types](/programming-guides/proto3#scalar). A field can also be of: @@ -248,7 +245,7 @@ A field can also be of: * A `map` type, to add key-value pairs to your definition. Messages can allow **extensions** to define fields outside of the message, -itself. For example, the protobuf library's internal message schema allows +itself. For example, the Protobuf library's internal message schema allows extensions for custom, usage-specific options. For more information about the options available, see the language guide for @@ -272,35 +269,34 @@ number. ## Additional Data Type Support {#data-types} -Protocol buffers support many scalar value types, including integers that use -both variable-length encoding and fixed sizes. You can also create your own -composite data types by defining messages that are, themselves, data types that -you can assign to a field. In addition to the simple and composite value types, -several +Protobuf supports many scalar value types, including integers that use both +variable-length encoding and fixed sizes. You can also create your own composite +data types by defining messages that are, themselves, data types that you can +assign to a field. In addition to the simple and composite value types, several [common types](/best-practices/dos-donts#well-known-common) are published. ## History {#history} -To read about the history of the protocol buffers project, see -[History of Protocol Buffers](/history). +To read about the history of the Protobuf project, see +[History of Protobuf](/history). -## Protocol Buffers Open Source Philosophy {#philosophy} +## Protobuf Open Source Philosophy {#philosophy} -Protocol buffers were open sourced in 2008 as a way to provide developers -outside of Google with the same benefits that we derive from them internally. We -support the open source community through regular updates to the language as we -make those changes to support our internal requirements. While we accept select -pull requests from external developers, we cannot always prioritize feature -requests and bug fixes that don’t conform to Google’s specific needs. +Protobuf was open sourced in 2008 as a way to provide developers outside of +Google with the same benefits that we derive from it internally. We support the +open source community through regular updates to the language as we make those +changes to support our internal requirements. While we accept select pull +requests from external developers, we cannot always prioritize feature requests +and bug fixes that don’t conform to Google’s specific needs. ## Developer Community {#community} -To be alerted to upcoming changes in Protocol Buffers and to connect with -protobuf developers and users, +To be alerted to upcoming changes in Protobuf and to connect with Protobuf +developers and users, [join the Google Group](https://groups.google.com/g/protobuf). ## Additional Resources {#additional-resources} -* [Protocol Buffers GitHub](https://github.com/protocolbuffers/protobuf/) +* [Protobuf GitHub](https://github.com/protocolbuffers/protobuf/) * [Tutorials](https://protobuf.dev/getting-started/) diff --git a/content/programming-guides/_index.md b/content/programming-guides/_index.md index 38f09fd4e..7cb7e83fb 100644 --- a/content/programming-guides/_index.md +++ b/content/programming-guides/_index.md @@ -1,6 +1,6 @@ +++ title = "Programming Guides" weight = 27 -description = "Learn how to use Protocol Buffers in your projects." +description = "Learn how to use Protobuf in your projects." type = "docs" +++ diff --git a/content/programming-guides/addons.md b/content/programming-guides/addons.md index 6213e5454..555ef70a4 100644 --- a/content/programming-guides/addons.md +++ b/content/programming-guides/addons.md @@ -2,10 +2,10 @@ title = "Third-Party Add-ons" weight = 80 linkTitle = "Add-ons" -description = "Links out to many open source projects that seek to add useful functionality on top of Protocol Buffers." +description = "Links out to many open source projects that seek to add useful functionality on top of Protobuf." type = "docs" +++ -Many open source projects seek to add useful functionality on top of Protocol -Buffers. For a list of links to projects we know about, see the +Many open source projects seek to add useful functionality on top of Protobuf. +For a list of links to projects we know about, see the [third-party add-ons wiki page](https://github.com/protocolbuffers/protobuf/blob/master/docs/third_party.md). diff --git a/content/programming-guides/deserialize-debug.md b/content/programming-guides/deserialize-debug.md index 6e4a75949..9f157efae 100644 --- a/content/programming-guides/deserialize-debug.md +++ b/content/programming-guides/deserialize-debug.md @@ -1,7 +1,7 @@ +++ title = "Deserializing Debug Proto Representations" weight = 89 -description = "How to log debugging information in Protocol Buffers." +description = "How to log debugging information in Protobuf." type = "docs" +++ @@ -46,14 +46,14 @@ not set in the proto.** ## Why is this URL here? We want to make sure nobody deserializes human-readable representations of a -protobuf message intended for humans debugging a system. Historically, +Protobuf message intended for humans debugging a system. Historically, `.DebugString()` and `TextFormat` were interchangeable, and existing systems use DebugString to transport and store data. We want to make sure sensitive data does not accidentally end up in logs. -Therefore, we are transparently redacting some field values from protobuf -messages before turning them into a string -("[REDACTED]"). This reduces the security & privacy +Therefore, we are transparently redacting some field values from Protobuf +messages before turning them into a +string ("[REDACTED]"). This reduces the security & privacy risk of accidental logging, but risks data loss if other systems deserialize your message. To address this risk, we are intentionally splitting the machine-readable TextFormat from the human-readable debug format to be used in @@ -105,7 +105,7 @@ making sure your configuration files don't contain any PII. ### I Am Writing a Unit Test, and Want to Compare Debugstring in a Test Assertion -If you want to compare protobuf values, use `MessageDifferencer` like in the +If you want to compare Protobuf values, use `MessageDifferencer` like in the following: ```cpp diff --git a/content/programming-guides/editions.md b/content/programming-guides/editions.md index bc12adc1d..ab560b489 100644 --- a/content/programming-guides/editions.md +++ b/content/programming-guides/editions.md @@ -1,15 +1,15 @@ +++ title = "Language Guide (editions)" weight = 40 -description = "Covers how to use the editions revisions of the Protocol Buffers language in your project." +description = "Covers how to use the editions revisions of the Protobuf language in your project." type = "docs" +++ -This guide describes how to use the protocol buffer language to structure your -protocol buffer data, including `.proto` file syntax and how to generate data -access classes from your `.proto` files. It covers **edition 2023** to **edition -2024** of the protocol buffers language. For information about how editions -differ from proto2 and proto3 conceptually, see +This guide describes how to use the Protobuf language to structure your Protobuf +data, including `.proto` file syntax and how to generate data access classes +from your `.proto` files. It covers **edition 2023** to **edition 2024** of the +Protobuf language. For information about how editions differ from proto2 and +proto3 conceptually, see [Protobuf Editions Overview](/editions/overview). For information on the **proto2** syntax, see the @@ -41,12 +41,12 @@ message SearchRequest { ``` * The first line of the file specifies that you're using edition 2023 of the - protobuf language spec. + Protobuf language spec. * The `edition` (or `syntax` for proto2/proto3) must be the first non-empty, non-comment line of the file. - * If no `edition` or `syntax` is specified, the protocol buffer compiler - will assume you are using + * If no `edition` or `syntax` is specified, the Protobuf compiler will + assume you are using [proto2](/programming-guides/proto2). * The `SearchRequest` message definition specifies three fields (name/value @@ -66,9 +66,9 @@ You must give each field in your message definition a number between `1` and `536,870,911` with the following restrictions: - The given number **must be unique** among all fields for that message. -- Field numbers `19,000` to `19,999` are reserved for the Protocol Buffers - implementation. The protocol buffer compiler will complain if you use one of - these reserved field numbers in your message. +- Field numbers `19,000` to `19,999` are reserved for the Protobuf + implementation. The Protobuf compiler will complain if you use one of these + reserved field numbers in your message. - You cannot use any previously [reserved](#fieldreserved) field numbers or any field numbers that have been allocated to [extensions](#extensions). @@ -88,13 +88,13 @@ fields. Lower field number values take less space in the wire format. For example, field numbers in the range 1 through 15 take one byte to encode. Field numbers in the range 16 through 2047 take two bytes. You can find out more about this in -[Protocol Buffer Encoding](/programming-guides/encoding#structure). +[Protobuf Encoding](/programming-guides/encoding#structure). #### Consequences of Reusing Field Numbers {#consequences} Reusing a field number makes decoding wire-format messages ambiguous. -The protobuf wire format is lean and doesn't provide a way to detect fields +The Protobuf wire format is lean and doesn't provide a way to detect fields encoded using one definition and decoded using another. Encoding a field using one definition and then decoding that same field with a @@ -160,11 +160,11 @@ In proto editions, `repeated` fields of scalar numeric types use `packed` encoding by default. You can find out more about `packed` encoding in -[Protocol Buffer Encoding](/programming-guides/encoding#packed). +[Protobuf Encoding](/programming-guides/encoding#packed). #### Well-formed Messages {#well-formed} -The term "well-formed," when applied to protobuf messages, refers to the bytes +The term "well-formed," when applied to Protobuf messages, refers to the bytes serialized/deserialized. The protoc parser validates that a given proto definition file is parseable. @@ -284,11 +284,11 @@ statement. ### What's Generated from Your `.proto`? {#generated} -When you run the [protocol buffer compiler](#generating) on a `.proto`, the -compiler generates the code in your chosen language you'll need to work with the -message types you've described in the file, including getting and setting field -values, serializing your messages to an output stream, and parsing your messages -from an input stream. +When you run the [Protobuf compiler](#generating) on a `.proto`, the compiler +generates the code in your chosen language you'll need to work with the message +types you've described in the file, including getting and setting field values, +serializing your messages to an output stream, and parsing your messages from an +input stream. * For **C++**, the compiler generates a `.h` and `.cc` file from each `.proto`, with a class for each message type described in your file. @@ -630,7 +630,7 @@ machines. You can find out more about how these types are encoded when you serialize your message in -[Protocol Buffer Encoding](/programming-guides/encoding). +[Protobuf Encoding](/programming-guides/encoding). ## Default Field Values {#default} @@ -656,7 +656,7 @@ appropriate language). ### Overriding Default Scalar Values {#explicit-default} -In protobuf editions, you can specify explicit default values for singular +In Protobuf editions, you can specify explicit default values for singular non-message fields. For example, let's say you want to provide a default value of 10 for the `SearchRequest.result_per_page` field: @@ -750,9 +750,9 @@ 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 for serialization, only the first value -is used when deserializing. +Protobuf compiler generates a warning message when aliases are found. +Though all alias values are valid for serialization, only the first value is +used when deserializing. ```proto enum EnumAllowingAlias { @@ -784,7 +784,7 @@ 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 +When you run the Protobuf 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 symbolic constants with integer values in the runtime-generated class. @@ -823,10 +823,10 @@ own updates to the type. This can cause severe issues if they later load old instances of the same `.proto`, including data corruption, privacy bugs, and so on. One way to make sure this doesn't happen is to specify that the numeric values (and/or names, which can also cause issues for JSON serialization) of -your deleted entries are `reserved`. The protocol buffer compiler will complain -if any future users try to use these identifiers. You can specify that your -reserved numeric value range goes up to the maximum possible value using the -`max` keyword. +your deleted entries are `reserved`. The Protobuf compiler will complain if any +future users try to use these identifiers. You can specify that your reserved +numeric value range goes up to the maximum possible value using the `max` +keyword. ```proto enum Foo { @@ -1006,9 +1006,8 @@ wire format. {{% alert title="Note" color="note" %}} If you use ProtoJSON or [proto text format](/reference/protobuf/textformat-spec) -to store your protocol buffer messages, the changes that you can make in your -proto definition are different. The ProtoJSON wire format safe changes are -described +to store your Protobuf messages, the changes that you can make in your proto +definition are different. The ProtoJSON wire format safe changes are described [here](/programming-guides/json#json-wire-safety). {{% /alert %}} @@ -1122,10 +1121,10 @@ schema to know when the different range of values may be safe to use. ## Unknown Fields {#unknowns} -Unknown fields are well-formed protocol buffer serialized data representing -fields that the parser does not recognize. For example, when an old binary -parses data sent by a new binary with new fields, those new fields become -unknown fields in the old binary. +Unknown fields are well-formed Protobuf serialized data representing fields that +the parser does not recognize. For example, when an old binary parses data sent +by a new binary with new fields, those new fields become unknown fields in the +old binary. Editions messages preserve unknown fields and include them during parsing and in the serialized output, which matches proto2 and proto3 behavior. @@ -1241,7 +1240,7 @@ field so long as the field number, type, and cardinality remain constant. However, because extensions are defined outside of the container message, no specialized accessors are generated to get and set specific extension fields. -For our example, the protobuf compiler **will not generate** `AddKittenVideos()` +For our example, the Protobuf compiler **will not generate** `AddKittenVideos()` or `GetKittenVideos()` accessors. Instead, extensions are accessed through parameterized functions like: `HasExtension()`, `ClearExtension()`, `GetExtension()`, `MutableExtension()`, and `AddExtension()`. @@ -1360,17 +1359,17 @@ The next extension of `Container` should add a new declaration with the number The owner of a container message may choose to forgo extension declarations in favor of their own unverified extension number allocation strategy. -An unverified allocation scheme uses a mechanism external to the protobuf +An unverified allocation scheme uses a mechanism external to the Protobuf ecosystem to allocate extension field numbers within the selected extension range. One example could be using a monorepo's commit number. This system is -"unverified" from the protobuf compiler's point of view since there is no way to +"unverified" from the Protobuf compiler's point of view since there is no way to check that an extension is using a properly acquired extension field number. The benefit of an unverified system over a verified system like extension declarations is the ability to define an extension without coordinating with the container message owner. -The downside of an unverified system is that the protobuf compiler cannot +The downside of an unverified system is that the Protobuf compiler cannot protect participants from reusing extension field numbers. **Unverified extension field number allocation strategies are not recommended** @@ -1636,7 +1635,7 @@ wire is a member of the oneof. ## Maps {#maps} If you want to create an associative map as part of your data definition, -protocol buffers provides a handy shortcut syntax: +Protobuf provides a handy shortcut syntax: ```proto map map_field = N; @@ -1678,7 +1677,7 @@ can find out more about the map API for your chosen language in the relevant ### Backwards Compatibility {#backwards} -The map syntax is equivalent to the following on the wire, so protocol buffers +The map syntax is equivalent to the following on the wire, so Protobuf implementations that do not support maps can still handle your data: ```proto @@ -1690,8 +1689,8 @@ message MapFieldEntry { repeated MapFieldEntry map_field = N; ``` -Any protocol buffers implementation that supports maps must both produce and -accept data that can be accepted by the earlier definition. +Any Protobuf implementation that supports maps must both produce and accept data +that can be accepted by the earlier definition. ## Packages {#packages} @@ -1744,23 +1743,23 @@ conflicts in descriptors and make the proto not portable for other languages. ### Packages and Name Resolution {#name-resolution} -Type name resolution in the protocol buffer language works like C++: first the +Type name resolution in the Protobuf language works like C++: first the innermost scope is searched, then the next-innermost, and so on, with each package considered to be "inner" to its parent package. A leading '.' (for example, `.foo.bar.Baz`) means to start from the outermost scope instead. -The protocol buffer compiler resolves all type names by parsing the imported -`.proto` files. The code generator for each language knows how to refer to each -type in that language, even if it has different scoping rules. +The Protobuf compiler resolves all type names by parsing the imported `.proto` +files. The code generator for each language knows how to refer to each type in +that language, even if it has different scoping rules. ## Defining Services {#services} If you want to use your message types with an RPC (Remote Procedure Call) system, you can define an RPC service interface in a `.proto` file and the -protocol buffer compiler will generate service interface code and stubs in your -chosen language. So, for example, if you want to define an RPC service with a -method that takes your `SearchRequest` and returns a `SearchResponse`, you can -define it in your `.proto` file as follows: +Protobuf compiler will generate service interface code and stubs in your chosen +language. So, for example, if you want to define an RPC service with a method +that takes your `SearchRequest` and returns a `SearchResponse`, you can define +it in your `.proto` file as follows: ```proto service SearchService { @@ -1768,26 +1767,26 @@ service SearchService { } ``` -The most straightforward RPC system to use with protocol buffers is +The most straightforward RPC system to use with Protobuf is [gRPC](https://grpc.io): a language- and platform-neutral open source RPC system -developed at Google. gRPC works particularly well with protocol buffers and lets -you generate the relevant RPC code directly from your `.proto` files using a -special protocol buffer compiler plugin. +developed at Google. gRPC works particularly well with Protobuf and lets you +generate the relevant RPC code directly from your `.proto` files using a special +Protobuf compiler plugin. -If you don't want to use gRPC, it's also possible to use protocol buffers with -your own RPC implementation. You can find out more about this in the +If you don't want to use gRPC, it's also possible to use Protobuf with your own +RPC implementation. You can find out more about this in the [Proto2 Language Guide](/programming-guides/proto2#services). There are also a number of ongoing third-party projects to develop RPC -implementations for Protocol Buffers. For a list of links to projects we know -about, see the +implementations for Protobuf. For a list of links to projects we know about, see +the [third-party add-ons wiki page](https://github.com/protocolbuffers/protobuf/blob/master/docs/third_party.md). ## JSON Mapping {#json} -The standard protobuf binary wire format is the preferred serialization format -for communication between two systems that use protobufs. For communicating with -systems that use JSON rather than protobuf wire format, Protobuf supports a +The standard Protobuf binary wire format is the preferred serialization format +for communication between two systems that use Protobuf. For communicating with +systems that use JSON rather than the Protobuf wire format, Protobuf supports a canonical encoding in [ProtoJSON](/programming-guides/json). @@ -1853,19 +1852,18 @@ Here are a few of the most commonly used options: `LITE_RUNTIME`. This affects the C++ and Java code generators (and possibly third-party generators) in the following ways: - * `SPEED` (default): The protocol buffer compiler will generate code for + * `SPEED` (default): The Protobuf compiler will generate code for serializing, parsing, and performing other common operations on your 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 - 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 - blindingly fast. - * `LITE_RUNTIME`: The protocol buffer compiler will generate classes that - depend only on the "lite" runtime library (`libprotobuf-lite` instead of + * `CODE_SIZE`: The Protobuf compiler will generate minimal classes and + will rely on shared, reflection-based code to implement 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 blindingly fast. + * `LITE_RUNTIME`: The Protobuf compiler will generate classes that depend + only on the "lite" runtime library (`libprotobuf-lite` instead of `libprotobuf`). The lite runtime is much smaller than the full library (around an order of magnitude smaller) but omits certain features like descriptors and reflection. This is particularly useful for apps running @@ -1902,7 +1900,7 @@ Here are a few of the most commonly used options: [recommended by Apple](https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Conventions/Conventions.html#//apple_ref/doc/uid/TP40011210-CH10-SW4). Note that all 2 letter prefixes are reserved by Apple. -* `packed` (field option): In protobuf editions, this option is locked to +* `packed` (field option): In Protobuf editions, this option is locked to `true`. To use unpacked wireformat, you can override this option using an editions feature. This provides compatibility with parsers prior to version 2.3.0 (rarely needed) as shown in the following example: @@ -1962,9 +1960,9 @@ values and to fields. ### Custom Options {#customoptions} -Protocol Buffers also allows you to define and use your own options. Note that -this is an **advanced feature** which most people don't need. If you do think -you need to create your own options, see the +Protobuf also allows you to define and use your own options. Note that this is +an **advanced feature** which most people don't need. If you do think you need +to create your own options, see the [Proto2 Language Guide](/programming-guides/proto2#customoptions) for details. Note that creating custom options uses [extensions](/programming-guides/proto2#extensions). @@ -2011,10 +2009,10 @@ since it is the default behavior. When a message field is marked override that by trying to set `RETENTION_RUNTIME`. {{% alert title="Note" color="note" %}} As -of Protocol Buffers 22.0, support for option retention is still in progress and -only C++ and Java are supported. Go has support starting from 1.29.0. Python -support is complete but has not made it into a release yet. -{{% /alert %}} +of Protobuf 22.0, support for option retention is still in progress and only C++ +and Java are supported. Go has support starting from 1.29.0. Python support is +complete but has not made it into a release +yet. {{% /alert %}} ### Option Targets {#option-targets} @@ -2069,8 +2067,8 @@ enum MyEnum { To generate the Java, Kotlin, Python, C++, Go, Ruby, Objective-C, or C# code that you need to work with the message types defined in a `.proto` file, you -need to run the protocol buffer compiler `protoc` on the `.proto` file. If you -haven't installed the compiler, +need to run the Protobuf compiler `protoc` on the `.proto` file. If you haven't +installed the compiler, [download the package](/downloads) and follow the instructions in the README. For Go, you also need to install a special code generator plugin for the compiler; you can find this and installation diff --git a/content/programming-guides/encoding.md b/content/programming-guides/encoding.md index fbbc6eee7..242767293 100644 --- a/content/programming-guides/encoding.md +++ b/content/programming-guides/encoding.md @@ -1,14 +1,14 @@ +++ title = "Encoding" weight = 60 -description = "Explains how Protocol Buffers encodes data to files or to the wire." +description = "Explains how Protobuf encodes data to files or to the wire." type = "docs" +++ -This document describes the protocol buffer *wire format*, which defines the -details of how your message is sent on the wire and how much space it consumes -on disk. You probably don't need to understand this to use protocol buffers in -your application, but it's useful information for doing optimizations. +This document describes the Protobuf *wire format*, which defines the details of +how your message is sent on the wire and how much space it consumes on disk. You +probably don't need to understand this to use Protobuf in your application, but +it's useful information for doing optimizations. If you already know the concepts but want a reference, skip to the [Condensed reference card](#cheat-sheet) section. @@ -26,7 +26,7 @@ denote UTF-8 strings, like `"Hello, Protobuf!"`. This literal is synonymous with composed of ASCII bytes). We'll introduce more of the Protoscope language as we discuss aspects of the wire format. -The Protoscope tool can also dump encoded protocol buffers as text. See +The Protoscope tool can also dump encoded Protobuf messages as text. See https://github.com/protocolbuffers/protoscope/tree/main/testdata for examples. All examples in this topic assume that you are using Edition 2023 or later. @@ -94,13 +94,13 @@ order, concatenate, and interpret as an unsigned 64-bit integer: 128 + 16 + 4 + 2 = 150 // Interpret as an unsigned 64-bit integer. ``` -Because varints are so crucial to protocol buffers, in protoscope syntax, we -refer to them as plain integers. `150` is the same as `` `9601` ``. +Because varints are so crucial to Protobuf, in protoscope syntax, we refer to +them as plain integers. `150` is the same as `` `9601` ``. ## Message Structure {#structure} -A protocol buffer message is a series of key-value pairs. The binary version of -a message just uses the field's number as the key -- the name and declared type +A Protobuf message is a series of key-value pairs. The binary version of a +message just uses the field's number as the key -- the name and declared type for each field can only be determined on the decoding end by referencing the message type's definition (i.e. the `.proto` file). Protoscope does not have access to this information, so it can only provide the field numbers. @@ -163,10 +163,10 @@ always encode as either `` `00` `` or `` `01` ``. In Protoscope, `false` and ### Signed Integers {#signed-ints} -As you saw in the previous section, all the protocol buffer types associated -with wire type 0 are encoded as varints. However, varints are unsigned, so the -different signed types, `sint32` and `sint64` vs `int32` or `int64`, encode -negative integers differently. +As you saw in the previous section, all the Protobuf types associated with wire +type 0 are encoded as varints. However, varints are unsigned, so the different +signed types, `sint32` and `sint64` vs `int32` or `int64`, encode negative +integers differently. The `intN` types encode negative numbers as two's complement, which means that, as unsigned, 64-bit integers, they have their highest bit set. As a result, this @@ -360,8 +360,8 @@ the same message above that parsers must accept: 5: {3} ``` -Protocol buffer parsers must be able to parse repeated fields that were compiled -as `packed` as if they were not packed, and vice versa. This permits adding +Protobuf parsers must be able to parse repeated fields that were compiled as +`packed` as if they were not packed, and vice versa. This permits adding `[packed=true]` to existing fields in a forward- and backward-compatible way. ### Oneofs {#oneofs} @@ -473,33 +473,33 @@ When a message is serialized, there is no guaranteed order for how its known or [unknown fields](/programming-guides/proto2#updating) will be written. Serialization order is an implementation detail, and the details of any particular implementation may change in the future. Therefore, -protocol buffer parsers must be able to parse fields in any order. +Protobuf parsers must be able to parse fields in any order. ### Implications {#implications} * Do not assume the byte output of a serialized message is stable. This is especially true for messages with transitive bytes fields representing other - serialized protocol buffer messages. + serialized Protobuf messages. * By default, repeated invocations of serialization methods on the same - protocol buffer message instance may not produce the same byte output. That - is, the default serialization is not deterministic. + Protobuf message instance may not produce the same byte output. That is, the + default serialization is not deterministic. * Deterministic serialization only guarantees the same byte output for a particular binary. The byte output may change across different versions of the binary. -* The following checks may fail for a protocol buffer message instance `foo`: +* The following checks may fail for a Protobuf message instance `foo`: * `foo.SerializeAsString() == foo.SerializeAsString()` * `Hash(foo.SerializeAsString()) == Hash(foo.SerializeAsString())` * `CRC(foo.SerializeAsString()) == CRC(foo.SerializeAsString())` * `FingerPrint(foo.SerializeAsString()) == FingerPrint(foo.SerializeAsString())` -* Here are a few example scenarios where logically equivalent protocol buffer +* Here are a few example scenarios where logically equivalent Protobuf messages `foo` and `bar` may serialize to different byte outputs: * `bar` is serialized by an old server that treats some fields as unknown. * `bar` is serialized by a server that is implemented in a different programming language and serializes fields in different order. * `bar` has a field that serializes in a non-deterministic manner. - * `bar` has a field that stores a serialized byte output of a protocol - buffer message which is serialized differently. + * `bar` has a field that stores a serialized byte output of a Protobuf + message which is serialized differently. * `bar` is serialized by a new server that serializes fields in a different order due to an implementation change. * `foo` and `bar` are concatenations of the same individual messages in a diff --git a/content/programming-guides/enum.md b/content/programming-guides/enum.md index 64b6fe170..0ea887f11 100644 --- a/content/programming-guides/enum.md +++ b/content/programming-guides/enum.md @@ -1,12 +1,12 @@ +++ title = "Enum Behavior" weight = 55 -description = "Explains how enums currently work in Protocol Buffers vs. how they should work." +description = "Explains how enums currently work in Protobuf vs. how they should work." type = "docs" +++ Enums behave differently in different language libraries. This topic covers the -different behaviors as well as the plans to move protobufs to a state where they +different behaviors as well as the plans to move Protobuf to a state where enums are consistent across all languages. If you're looking for information on how to use enums in general, see the corresponding sections in the [proto2](/programming-guides/proto2#enum), @@ -86,7 +86,7 @@ explicitly set editions enums to closed, if needed. ## Specification {#spec} -The following specifies the behavior of conformant implementations for protobuf. +The following specifies the behavior of conformant implementations for Protobuf. Because this is subtle, many implementations are out of conformance. See [Known Issues](#known-issues) for details on how different implementations behave. diff --git a/content/programming-guides/field_presence.md b/content/programming-guides/field_presence.md index 23a02d217..d9a4b5405 100644 --- a/content/programming-guides/field_presence.md +++ b/content/programming-guides/field_presence.md @@ -2,14 +2,14 @@ title = "Application Note: Field Presence" weight = 85 linkTitle = "Field Presence" -description = "Explains the various presence-tracking disciplines for protobuf fields. It also explains the behavior of explicit presence-tracking for singular proto3 fields with basic types." +description = "Explains the various presence-tracking disciplines for Protobuf fields. It also explains the behavior of explicit presence-tracking for singular proto3 fields with basic types." type = "docs" +++ ## Background {#background} -*Field presence* is the notion of whether a protobuf field has a value. There -are two different manifestations of presence for protobufs: *implicit presence*, +*Field presence* is the notion of whether a Protobuf field has a value. There +are two different manifestations of presence in Protobuf: *implicit presence*, where the generated message API stores field values (only), and *explicit presence*, where the API also stores whether or not a field has been set. @@ -71,8 +71,8 @@ deserializing wire-formatted messages: ### Presence in *Named-field Mapping* Formats {#presence-named-field} -Protobufs can be represented in human-readable, textual forms. Two notable -formats are TextFormat (the output format produced by generated message +Protobuf messages can be represented in human-readable, textual forms. Two +notable formats are TextFormat (the output format produced by generated message `DebugString` methods) and JSON. These formats have correctness requirements of their own, and are generally @@ -105,7 +105,7 @@ semantics of the wire format or TextFormat. In theory, JSON *can* represent presence in a semantic-preserving fashion. In practice, however, presence correctness can vary depending upon implementation choices, especially if JSON was chosen as a means to interoperate with clients -not using protobufs. +not using Protobuf. ### Presence in Proto2 APIs {#presence-proto2} @@ -127,7 +127,7 @@ The generated message interface includes methods to query presence of fields. For example, the field `foo` has a corresponding `has_foo` method. (The specific name follows the same language-specific naming convention as the field accessors.) These methods are sometimes referred to as "hazzers" within the -protobuf implementation. +Protobuf implementation. Similar to singular fields, `oneof` fields explicitly track which one of the members, if any, contains a value. For example, consider this example `oneof`: @@ -247,16 +247,14 @@ proto schema files.{{% /alert %}} ### Considerations for Merging {#merging} -Under the *implicit presence* rules, it is effectively impossible for a target -field to merge-from its default value (using the protobuf's API merging -functions). This is because default values are skipped, similar to the *implicit -presence* serialization discipline. Merging only updates the target (merged-to) -message using the non-skipped values from the update (merged-from) message. +Under the *implicit presence* rules, when merging values any default-valued +field is skipped; there is no signal to distinguish if the field was never-set +or if it was set to zero. -The difference in merging behavior has further implications for protocols which -rely on partial "patch" updates. If field presence is not tracked, then an -update patch alone cannot represent an update to the default value, because only -non-default values are merged-from. +The implication of the merging behavior has implications for protocols which +rely on partial "patch" updates. Since field presence is not tracked, you can +signal a field should be replaced for a non-default value (e.g. `42`) but not +for a default value (e.g. `0`). Updating to set a default value in this case requires some external mechanism, such as `FieldMask`. However, if presence *is* tracked, then all explicitly-set diff --git a/content/programming-guides/json.md b/content/programming-guides/json.md index ddf199af8..f24ca699d 100644 --- a/content/programming-guides/json.md +++ b/content/programming-guides/json.md @@ -6,7 +6,7 @@ type = "docs" +++ Protobuf supports a canonical encoding in JSON, making it easier to share data -with systems that do not support the standard protobuf binary wire format. +with systems that do not support the standard Protobuf binary wire format. This page specifies the format, but a number of additional edge cases which define a conformant ProtoJSON parser are covered in the Protobuf Conformance @@ -267,7 +267,7 @@ the value of a `string` field. ### Presence and default-values {#presence} -When generating JSON-encoded output from a protocol buffer, if a field supports +When generating JSON-encoded output from a Protobuf message, if a field supports presence, serializers must emit the field value if and only if the corresponding hazzer would return true. @@ -681,10 +681,10 @@ precisely represent nanosecond precision (like `10.500000001s`). ## Non-Round Trippable Edge cases of Well-Known Types {#wkt-roundtrip-limitations} -While ProtoJSON defines canonical JSON representations for all Protocol Buffer -types, under some edge cases Well-Known Types are not supported to round-trip -cleanly (i.e., deserializing JSON back into proto, or vice versa) due to design -bugs in the format. +While ProtoJSON defines canonical JSON representations for all Protobuf types, +under some edge cases Well-Known Types are not supported to round-trip cleanly +(i.e., deserializing JSON back into proto, or vice versa) due to design bugs in +the format. For example, `google.protobuf.Value` has a double field for JSON numbers. JSON numbers can represent any double except for `Infinity`, `-Infinity` and `NaN`; @@ -729,7 +729,7 @@ prevent issues. ## JSON Options {#json-options} -A conformant protobuf JSON implementation may provide the following options: +A conformant Protobuf JSON implementation may provide the following options: * **Always emit fields without presence**: Fields that don't support presence and that have their default value are omitted by default in JSON output (for @@ -742,12 +742,12 @@ A conformant protobuf JSON implementation may provide the following options: this flag affects proto2 `optional` fields but not proto3 `optional` fields. A fix is planned for a future release. -* **Ignore unknown fields**: The protobuf JSON parser should reject unknown +* **Ignore unknown fields**: The Protobuf JSON parser should reject unknown fields by default but may provide an option to ignore unknown fields in parsing. * **Use proto field name instead of lowerCamelCase name**: By default the - protobuf JSON printer should convert the field name to lowerCamelCase and + Protobuf JSON printer should convert the field name to lowerCamelCase and use that as the JSON name. An implementation may provide an option to use proto field name as the JSON name instead. Protobuf JSON parsers are required to accept both the converted lowerCamelCase name and the proto diff --git a/content/programming-guides/proto2.md b/content/programming-guides/proto2.md index 00b368e23..0bd4cdac1 100644 --- a/content/programming-guides/proto2.md +++ b/content/programming-guides/proto2.md @@ -1,15 +1,15 @@ +++ title = "Language Guide (proto 2)" weight = 40 -description = "Covers how to use the proto2 revision of Protocol Buffers language in your project." +description = "Covers how to use the proto2 revision of the Protobuf language in your project." aliases = "/programming-guides/proto/" type = "docs" +++ -This guide describes how to use the protocol buffer language to structure your -protocol buffer data, including `.proto` file syntax and how to generate data -access classes from your `.proto` files. It covers the **proto2** revision of -the protocol buffers language. +This guide describes how to use the Protobuf language to structure your Protobuf +data, including `.proto` file syntax and how to generate data access classes +from your `.proto` files. It covers the **proto2** revision of the Protobuf +language. For information on **editions** syntax, see the [Protobuf Editions Language Guide](/programming-guides/editions). @@ -40,11 +40,11 @@ message SearchRequest { ``` * The first line of the file specifies that you're using the proto2 revision - of the protobuf language spec. + of the Protobuf language spec. * The `syntax` must be the first non-empty, non-comment line of the file. - * If no `syntax` is specified, the protocol buffer compiler will assume - you are using proto2. + * If no `syntax` is specified, the Protobuf compiler will assume you are + using proto2. * The `SearchRequest` message definition specifies three fields (name/value pairs), one for each piece of data that you want to include in this type of @@ -63,9 +63,9 @@ You must give each field in your message definition a number between `1` and `536,870,911` with the following restrictions: - The given number **must be unique** among all fields for that message. -- Field numbers `19,000` to `19,999` are reserved for the Protocol Buffers - implementation. The protocol buffer compiler will complain if you use one of - these reserved field numbers in your message. +- Field numbers `19,000` to `19,999` are reserved for the Protobuf + implementation. The Protobuf compiler will complain if you use one of these + reserved field numbers in your message. - You cannot use any previously [reserved](#fieldreserved) field numbers or any field numbers that have been allocated to [extensions](#extensions). @@ -85,13 +85,13 @@ fields. Lower field number values take less space in the wire format. For example, field numbers in the range 1 through 15 take one byte to encode. Field numbers in the range 16 through 2047 take two bytes. You can find out more about this in -[Protocol Buffer Encoding](/programming-guides/encoding#structure). +[Protobuf Encoding](/programming-guides/encoding#structure). #### Consequences of Reusing Field Numbers {#consequences} Reusing a field number makes decoding wire-format messages ambiguous. -The protobuf wire format is lean and doesn't provide a way to detect fields +The Protobuf wire format is lean and doesn't provide a way to detect fields encoded using one definition and decoded using another. Encoding a field using one definition and then decoding that same field with a @@ -166,7 +166,7 @@ repeated ProtoEnum results = 5 [packed = true]; ``` You can find out more about `packed` encoding in -[Protocol Buffer Encoding](/programming-guides/encoding#packed). +[Protobuf Encoding](/programming-guides/encoding#packed). #### Required is Strongly Deprecated {#required-deprecated} @@ -185,7 +185,7 @@ missing, which also causes the required value check to fail. #### Well-formed Messages {#well-formed} -The term "well-formed," when applied to protobuf messages, refers to the bytes +The term "well-formed," when applied to Protobuf messages, refers to the bytes serialized/deserialized. The protoc parser validates that a given proto definition file is parseable. @@ -312,11 +312,11 @@ statement. ### What's Generated from Your `.proto`? {#generated} -When you run the [protocol buffer compiler](#generating) on a `.proto`, the -compiler generates the code in your chosen language you'll need to work with the -message types you've described in the file, including getting and setting field -values, serializing your messages to an output stream, and parsing your messages -from an input stream. +When you run the [Protobuf compiler](#generating) on a `.proto`, the compiler +generates the code in your chosen language you'll need to work with the message +types you've described in the file, including getting and setting field values, +serializing your messages to an output stream, and parsing your messages from an +input stream. * For **C++**, the compiler generates a `.h` and `.cc` file from each `.proto`, with a class for each message type described in your file. @@ -659,7 +659,7 @@ machines. You can find out more about how these types are encoded when you serialize your message in -[Protocol Buffer Encoding](/programming-guides/encoding). +[Protobuf Encoding](/programming-guides/encoding). ## Default Field Values {#default} @@ -792,9 +792,9 @@ explicitly overridden like this: 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 for serialization, only the first value -is used when deserializing. +Protobuf compiler generates a warning message when aliases are found. +Though all alias values are valid for serialization, only the first value is +used when deserializing. ```proto enum EnumAllowingAlias { @@ -822,7 +822,7 @@ 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_`. -When you run the protocol buffer compiler on a `.proto` that uses an `enum`, the +When you run the Protobuf 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 symbolic constants with integer values in the runtime-generated class. @@ -866,10 +866,10 @@ own updates to the type. This can cause severe issues if they later load old instances of the same `.proto`, including data corruption, privacy bugs, and so on. One way to make sure this doesn't happen is to specify that the numeric values (and/or names, which can also cause issues for JSON serialization) of -your deleted entries are `reserved`. The protocol buffer compiler will complain -if any future users try to use these identifiers. You can specify that your -reserved numeric value range goes up to the maximum possible value using the -`max` keyword. +your deleted entries are `reserved`. The Protobuf compiler will complain if any +future users try to use these identifiers. You can specify that your reserved +numeric value range goes up to the maximum possible value using the `max` +keyword. ```proto enum Foo { @@ -1043,9 +1043,8 @@ wire format. {{% alert title="Note" color="note" %}} If you use ProtoJSON or [proto text format](/reference/protobuf/textformat-spec) -to store your protocol buffer messages, the changes that you can make in your -proto definition are different. The ProtoJSON wire format safe changes are -described +to store your Protobuf messages, the changes that you can make in your proto +definition are different. The ProtoJSON wire format safe changes are described [here](/programming-guides/json#json-wire-safety). {{% /alert %}} @@ -1159,10 +1158,10 @@ schema to know when the different range of values may be safe to use. ## Unknown Fields {#unknowns} -Unknown fields are well-formed protocol buffer serialized data representing -fields that the parser does not recognize. For example, when an old binary -parses data sent by a new binary with new fields, those new fields become -unknown fields in the old binary. +Unknown fields are well-formed Protobuf serialized data representing fields that +the parser does not recognize. For example, when an old binary parses data sent +by a new binary with new fields, those new fields become unknown fields in the +old binary. Proto2 messages preserve unknown fields and include them during parsing and in the serialized output. @@ -1283,7 +1282,7 @@ field so long as the field number, type, and cardinality remain constant. However, because extensions are defined outside of the container message, no specialized accessors are generated to get and set specific extension fields. -For our example, the protobuf compiler **will not generate** `AddKittenVideos()` +For our example, the Protobuf compiler **will not generate** `AddKittenVideos()` or `GetKittenVideos()` accessors. Instead, extensions are accessed through parameterized functions like: `HasExtension()`, `ClearExtension()`, `GetExtension()`, `MutableExtension()`, and `AddExtension()`. @@ -1402,17 +1401,17 @@ The next extension of `Container` should add a new declaration with the number The owner of a container message may choose to forgo extension declarations in favor of their own unverified extension number allocation strategy. -An unverified allocation scheme uses a mechanism external to the protobuf +An unverified allocation scheme uses a mechanism external to the Protobuf ecosystem to allocate extension field numbers within the selected extension range. One example could be using a monorepo's commit number. This system is -"unverified" from the protobuf compiler's point of view since there is no way to +"unverified" from the Protobuf compiler's point of view since there is no way to check that an extension is using a properly acquired extension field number. The benefit of an unverified system over a verified system like extension declarations is the ability to define an extension without coordinating with the container message owner. -The downside of an unverified system is that the protobuf compiler cannot +The downside of an unverified system is that the Protobuf compiler cannot protect participants from reusing extension field numbers. **Unverified extension field number allocation strategies are not recommended** @@ -1681,7 +1680,7 @@ wire is a member of the oneof. ## Maps {#maps} If you want to create an associative map as part of your data definition, -protocol buffers provides a handy shortcut syntax: +Protobuf provides a handy shortcut syntax: ```proto map map_field = N; @@ -1723,7 +1722,7 @@ can find out more about the map API for your chosen language in the relevant ### Backwards Compatibility {#backwards} -The map syntax is equivalent to the following on the wire, so protocol buffers +The map syntax is equivalent to the following on the wire, so Protobuf implementations that do not support maps can still handle your data: ```proto @@ -1735,8 +1734,8 @@ message MapFieldEntry { repeated MapFieldEntry map_field = N; ``` -Any protocol buffers implementation that supports maps must both produce and -accept data that can be accepted by the earlier definition. +Any Protobuf implementation that supports maps must both produce and accept data +that can be accepted by the earlier definition. ## Packages {#packages} @@ -1789,23 +1788,23 @@ conflicts in descriptors and make the proto not portable for other languages. ### Packages and Name Resolution {#name-resolution} -Type name resolution in the protocol buffer language works like C++: first the +Type name resolution in the Protobuf language works like C++: first the innermost scope is searched, then the next-innermost, and so on, with each package considered to be "inner" to its parent package. A leading '.' (for example, `.foo.bar.Baz`) means to start from the outermost scope instead. -The protocol buffer compiler resolves all type names by parsing the imported -`.proto` files. The code generator for each language knows how to refer to each -type in that language, even if it has different scoping rules. +The Protobuf compiler resolves all type names by parsing the imported `.proto` +files. The code generator for each language knows how to refer to each type in +that language, even if it has different scoping rules. ## Defining Services {#services} If you want to use your message types with an RPC (Remote Procedure Call) system, you can define an RPC service interface in a `.proto` file and the -protocol buffer compiler will generate service interface code and stubs in your -chosen language. So, for example, if you want to define an RPC service with a -method that takes your `SearchRequest` and returns a `SearchResponse`, you can -define it in your `.proto` file as follows: +Protobuf compiler will generate service interface code and stubs in your chosen +language. So, for example, if you want to define an RPC service with a method +that takes your `SearchRequest` and returns a `SearchResponse`, you can define +it in your `.proto` file as follows: ```proto service SearchService { @@ -1897,25 +1896,25 @@ int main() { If you don't want to plug in your own existing RPC system, you can use [gRPC](https://github.com/grpc/grpc-common): a language- and platform-neutral open source RPC system developed at Google. gRPC works particularly well with -protocol buffers and lets you generate the relevant RPC code directly from your -`.proto` files using a special protocol buffer compiler plugin. However, as -there are potential compatibility issues between clients and servers generated -with proto2 and proto3, we recommend that you use proto3 or edition 2023 for -defining gRPC services. You can find out more about proto3 syntax in the +Protobuf and lets you generate the relevant RPC code directly from your `.proto` +files using a special Protobuf compiler plugin. However, as there are potential +compatibility issues between clients and servers generated with proto2 and +proto3, we recommend that you use proto3 or edition 2023 for defining gRPC +services. You can find out more about proto3 syntax in the [Proto3 Language Guide](/programming-guides/proto3) and about edition 2023 in [Edition 2023 Language Guide](/programming-guides/editions). In addition to gRPC, there are also a number of ongoing third-party projects to -develop RPC implementations for Protocol Buffers. For a list of links to -projects we know about, see the +develop RPC implementations for Protobuf. For a list of links to projects we +know about, see the [third-party add-ons wiki page](https://github.com/protocolbuffers/protobuf/blob/master/docs/third_party.md). ## JSON Mapping {#json} -The standard protobuf binary wire format is the preferred serialization format -for communication between two systems that use protobufs. For communicating with -systems that use JSON rather than protobuf wire format, Protobuf supports a +The standard Protobuf binary wire format is the preferred serialization format +for communication between two systems that use Protobuf. For communicating with +systems that use JSON rather than the Protobuf wire format, Protobuf supports a canonical encoding in [JSON](/programming-guides/json). ## Options {#options} @@ -1979,19 +1978,18 @@ Here are a few of the most commonly used options: `LITE_RUNTIME`. This affects the C++ and Java code generators (and possibly third-party generators) in the following ways: - * `SPEED` (default): The protocol buffer compiler will generate code for + * `SPEED` (default): The Protobuf compiler will generate code for serializing, parsing, and performing other common operations on your 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 - 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 - blindingly fast. - * `LITE_RUNTIME`: The protocol buffer compiler will generate classes that - depend only on the "lite" runtime library (`libprotobuf-lite` instead of + * `CODE_SIZE`: The Protobuf compiler will generate minimal classes and + will rely on shared, reflection-based code to implement 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 blindingly fast. + * `LITE_RUNTIME`: The Protobuf compiler will generate classes that depend + only on the "lite" runtime library (`libprotobuf-lite` instead of `libprotobuf`). The lite runtime is much smaller than the full library (around an order of magnitude smaller) but omits certain features like descriptors and reflection. This is particularly useful for apps running @@ -2050,7 +2048,7 @@ Here are a few of the most commonly used options: existing field to packed format without breaking wire compatibility. In 2.3.0 and later, this change is safe, as parsers for packable fields will always accept both formats, but be careful if you have to deal with old - programs using old protobuf versions. + programs using old Protobuf versions. ```proto repeated int32 samples = 4 [packed = true]; @@ -2107,9 +2105,9 @@ values and to fields. ### Custom Options {#customoptions} -Protocol Buffers also allows you to define and use your own options. Note that -this is an **advanced feature** which most people don't need. Since options are -defined by the messages defined in `google/protobuf/descriptor.proto` (like +Protobuf also allows you to define and use your own options. Note that this is +an **advanced feature** which most people don't need. Since options are defined +by the messages defined in `google/protobuf/descriptor.proto` (like `FileOptions` or `FieldOptions`), defining your own options is simply a matter of [extending](#extensions) those messages. For example: @@ -2152,8 +2150,8 @@ value = my_proto_file_pb2.MyMessage.DESCRIPTOR.GetOptions() .Extensions[my_proto_file_pb2.my_option] ``` -Custom options can be defined for every kind of construct in the Protocol -Buffers language. Here is an example that uses every kind of option: +Custom options can be defined for every kind of construct in the Protobuf +language. Here is an example that uses every kind of option: ```proto import "google/protobuf/descriptor.proto"; @@ -2248,8 +2246,8 @@ within individual organizations, so you can use numbers in this range freely for in-house applications. If you intend to use custom options in public applications, however, then it is important that you make sure that your field numbers are globally unique. To obtain globally unique field numbers, send a -request to add an entry to -[protobuf global extension registry](https://github.com/protocolbuffers/protobuf/blob/master/docs/options.md). +request to add an entry to the +[Protobuf global extension registry](https://github.com/protocolbuffers/protobuf/blob/master/docs/options.md). Usually you only need one extension number. You can declare multiple options with only one extension number by putting them in a sub-message: @@ -2314,10 +2312,10 @@ since it is the default behavior. When a message field is marked override that by trying to set `RETENTION_RUNTIME`. {{% alert title="Note" color="note" %}} As -of Protocol Buffers 22.0, support for option retention is still in progress and -only C++ and Java are supported. Go has support starting from 1.29.0. Python -support is complete but has not made it into a release yet. -{{% /alert %}} +of Protobuf 22.0, support for option retention is still in progress and only C++ +and Java are supported. Go has support starting from 1.29.0. Python support is +complete but has not made it into a release +yet. {{% /alert %}} ### Option Targets {#option-targets} @@ -2372,8 +2370,8 @@ enum MyEnum { To generate the Java, Kotlin, Python, C++, Go, Ruby, Objective-C, or C# code that you need to work with the message types defined in a `.proto` file, you -need to run the protocol buffer compiler `protoc` on the `.proto` file. If you -haven't installed the compiler, +need to run the Protobuf compiler `protoc` on the `.proto` file. If you haven't +installed the compiler, [download the package](/downloads) and follow the instructions in the README. For Go, you also need to install a special code generator plugin for the compiler; you can find this and installation diff --git a/content/programming-guides/proto3.md b/content/programming-guides/proto3.md index d93edd975..113eb1b39 100644 --- a/content/programming-guides/proto3.md +++ b/content/programming-guides/proto3.md @@ -1,14 +1,14 @@ +++ title = "Language Guide (proto 3)" weight = 40 -description = "Covers how to use the proto3 revision of the Protocol Buffers language in your project." +description = "Covers how to use the proto3 revision of the Protobuf language in your project." type = "docs" +++ -This guide describes how to use the protocol buffer language to structure your -protocol buffer data, including `.proto` file syntax and how to generate data -access classes from your `.proto` files. It covers the **proto3** revision of -the protocol buffers language. +This guide describes how to use the Protobuf language to structure your Protobuf +data, including `.proto` file syntax and how to generate data access classes +from your `.proto` files. It covers the **proto3** revision of the Protobuf +language. For information on **editions** syntax, see the [Protobuf Editions Language Guide](/programming-guides/editions). @@ -39,12 +39,12 @@ message SearchRequest { ``` * The first line of the file specifies that you're using the proto3 revision - of the protobuf language spec. + of the Protobuf language spec. * The `edition` (or `syntax` for proto2/proto3) must be the first non-empty, non-comment line of the file. - * If no `edition` or `syntax` is specified, the protocol buffer compiler - will assume you are using + * If no `edition` or `syntax` is specified, the Protobuf compiler will + assume you are using [proto2](/programming-guides/proto2). * The `SearchRequest` message definition specifies three fields (name/value @@ -64,9 +64,9 @@ You must give each field in your message definition a number between `1` and `536,870,911` with the following restrictions: - The given number **must be unique** among all fields for that message. -- Field numbers `19,000` to `19,999` are reserved for the Protocol Buffers - implementation. The protocol buffer compiler will complain if you use one of - these reserved field numbers in your message. +- Field numbers `19,000` to `19,999` are reserved for the Protobuf + implementation. The Protobuf compiler will complain if you use one of these + reserved field numbers in your message. - You cannot use any previously [reserved](#fieldreserved) field numbers or any field numbers that have been allocated to [extensions](/programming-guides/proto2#extensions). @@ -87,13 +87,13 @@ fields. Lower field number values take less space in the wire format. For example, field numbers in the range 1 through 15 take one byte to encode. Field numbers in the range 16 through 2047 take two bytes. You can find out more about this in -[Protocol Buffer Encoding](/programming-guides/encoding#structure). +[Protobuf Encoding](/programming-guides/encoding#structure). #### Consequences of Reusing Field Numbers {#consequences} Reusing a field number makes decoding wire-format messages ambiguous. -The protobuf wire format is lean and doesn't provide a way to detect fields +The Protobuf wire format is lean and doesn't provide a way to detect fields encoded using one definition and decoded using another. Encoding a field using one definition and then decoding that same field with a @@ -138,7 +138,7 @@ Message fields can be one of the following: You can check to see if the value was explicitly set. `optional` is recommended over *implicit* fields for maximum - compatibility with protobuf editions and proto2. + compatibility with Protobuf editions and proto2. * *implicit*: (not recommended) An implicit field has no explicit cardinality label and behaves as follows: @@ -169,7 +169,7 @@ In proto3, `repeated` fields of scalar numeric types use `packed` encoding by default. You can find out more about `packed` encoding in -[Protocol Buffer Encoding](/programming-guides/encoding#packed). +[Protobuf Encoding](/programming-guides/encoding#packed). #### Message Type Fields Always Have Field Presence {#field-presence} @@ -198,7 +198,7 @@ message Message3 { #### Well-formed Messages {#well-formed} -The term "well-formed," when applied to protobuf messages, refers to the bytes +The term "well-formed," when applied to Protobuf messages, refers to the bytes serialized/deserialized. The protoc parser validates that a given proto definition file is parseable. @@ -318,11 +318,11 @@ statement. ### What's Generated from Your `.proto`? {#generated} -When you run the [protocol buffer compiler](#generating) on a `.proto`, the -compiler generates the code in your chosen language you'll need to work with the -message types you've described in the file, including getting and setting field -values, serializing your messages to an output stream, and parsing your messages -from an input stream. +When you run the [Protobuf compiler](#generating) on a `.proto`, the compiler +generates the code in your chosen language you'll need to work with the message +types you've described in the file, including getting and setting field values, +serializing your messages to an output stream, and parsing your messages from an +input stream. * For **C++**, the compiler generates a `.h` and `.cc` file from each `.proto`, with a class for each message type described in your file. @@ -670,7 +670,7 @@ machines. You can find out more about how these types are encoded when you serialize your message in -[Protocol Buffer Encoding](/programming-guides/encoding). +[Protobuf Encoding](/programming-guides/encoding). ## Default Field Values {#default} @@ -786,9 +786,9 @@ other than "this value was unspecified". 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 for serialization, only the first value -is used when deserializing. +Protobuf compiler generates a warning message when aliases are found. +Though all alias values are valid for serialization, only the first value is +used when deserializing. ```proto enum EnumAllowingAlias { @@ -816,7 +816,7 @@ 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_`. -When you run the protocol buffer compiler on a `.proto` that uses an `enum`, the +When you run the Protobuf 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 symbolic constants with integer values in the runtime-generated class. @@ -855,10 +855,10 @@ own updates to the type. This can cause severe issues if they later load old instances of the same `.proto`, including data corruption, privacy bugs, and so on. One way to make sure this doesn't happen is to specify that the numeric values (and/or names, which can also cause issues for JSON serialization) of -your deleted entries are `reserved`. The protocol buffer compiler will complain -if any future users try to use these identifiers. You can specify that your -reserved numeric value range goes up to the maximum possible value using the -`max` keyword. +your deleted entries are `reserved`. The Protobuf compiler will complain if any +future users try to use these identifiers. You can specify that your reserved +numeric value range goes up to the maximum possible value using the `max` +keyword. ```proto enum Foo { @@ -903,7 +903,7 @@ file: import "myproject/other_protos.proto"; ``` -The protobuf compiler searches for imported files in a set of directories +The Protobuf compiler searches for imported files in a set of directories specified using the `-I`/`--proto_path` flag. The path given in an `import` statement is resolved relative to these directories. For more information on using the compiler, see [Generating Your Classes](#generating). @@ -1032,9 +1032,8 @@ wire format. {{% alert title="Note" color="note" %}} If you use ProtoJSON or [proto text format](/reference/protobuf/textformat-spec) -to store your protocol buffer messages, the changes that you can make in your -proto definition are different. The ProtoJSON wire format safe changes are -described +to store your Protobuf messages, the changes that you can make in your proto +definition are different. The ProtoJSON wire format safe changes are described [here](/programming-guides/json#json-wire-safety). {{% /alert %}} @@ -1148,10 +1147,10 @@ schema to know when the different range of values may be safe to use. ## Unknown Fields {#unknowns} -Unknown fields are well-formed protocol buffer serialized data representing -fields that the parser does not recognize. For example, when an old binary -parses data sent by a new binary with new fields, those new fields become -unknown fields in the old binary. +Unknown fields are well-formed Protobuf serialized data representing fields that +the parser does not recognize. For example, when an old binary parses data sent +by a new binary with new fields, those new fields become unknown fields in the +old binary. Proto3 messages preserve unknown fields and include them during parsing and in the serialized output, which matches proto2 behavior. @@ -1340,7 +1339,7 @@ wire is a member of the oneof. ## Maps {#maps} If you want to create an associative map as part of your data definition, -protocol buffers provides a handy shortcut syntax: +Protobuf provides a handy shortcut syntax: ```proto map map_field = N; @@ -1381,7 +1380,7 @@ can find out more about the map API for your chosen language in the relevant ### Backwards Compatibility {#backwards} -The map syntax is equivalent to the following on the wire, so protocol buffers +The map syntax is equivalent to the following on the wire, so Protobuf implementations that do not support maps can still handle your data: ```proto @@ -1393,8 +1392,8 @@ message MapFieldEntry { repeated MapFieldEntry map_field = N; ``` -Any protocol buffers implementation that supports maps must both produce and -accept data that can be accepted by the earlier definition. +Any Protobuf implementation that supports maps must both produce and accept data +that can be accepted by the earlier definition. ## Packages {#packages} @@ -1447,23 +1446,23 @@ conflicts in descriptors and make the proto not portable for other languages. ### Packages and Name Resolution {#name-resolution} -Type name resolution in the protocol buffer language works like C++: first the +Type name resolution in the Protobuf language works like C++: first the innermost scope is searched, then the next-innermost, and so on, with each package considered to be "inner" to its parent package. A leading '.' (for example, `.foo.bar.Baz`) means to start from the outermost scope instead. -The protocol buffer compiler resolves all type names by parsing the imported -`.proto` files. The code generator for each language knows how to refer to each -type in that language, even if it has different scoping rules. +The Protobuf compiler resolves all type names by parsing the imported `.proto` +files. The code generator for each language knows how to refer to each type in +that language, even if it has different scoping rules. ## Defining Services {#services} If you want to use your message types with an RPC (Remote Procedure Call) system, you can define an RPC service interface in a `.proto` file and the -protocol buffer compiler will generate service interface code and stubs in your -chosen language. So, for example, if you want to define an RPC service with a -method that takes your `SearchRequest` and returns a `SearchResponse`, you can -define it in your `.proto` file as follows: +Protobuf compiler will generate service interface code and stubs in your chosen +language. So, for example, if you want to define an RPC service with a method +that takes your `SearchRequest` and returns a `SearchResponse`, you can define +it in your `.proto` file as follows: ```proto service SearchService { @@ -1471,26 +1470,26 @@ service SearchService { } ``` -The most straightforward RPC system to use with protocol buffers is +The most straightforward RPC system to use with Protobuf is [gRPC](https://grpc.io): a language- and platform-neutral open source RPC system -developed at Google. gRPC works particularly well with protocol buffers and lets -you generate the relevant RPC code directly from your `.proto` files using a -special protocol buffer compiler plugin. +developed at Google. gRPC works particularly well with Protobuf and lets you +generate the relevant RPC code directly from your `.proto` files using a special +Protobuf compiler plugin. -If you don't want to use gRPC, it's also possible to use protocol buffers with -your own RPC implementation. You can find out more about this in the +If you don't want to use gRPC, it's also possible to use Protobuf with your own +RPC implementation. You can find out more about this in the [Proto2 Language Guide](/programming-guides/proto2#services). There are also a number of ongoing third-party projects to develop RPC -implementations for Protocol Buffers. For a list of links to projects we know -about, see the +implementations for Protobuf. For a list of links to projects we know about, see +the [third-party add-ons wiki page](https://github.com/protocolbuffers/protobuf/blob/master/docs/third_party.md). ## JSON Mapping {#json} -The standard protobuf binary wire format is the preferred serialization format -for communication between two systems that use protobufs. For communicating with -systems that use JSON rather than protobuf wire format, Protobuf supports a +The standard Protobuf binary wire format is the preferred serialization format +for communication between two systems that use Protobuf. For communicating with +systems that use JSON rather than the Protobuf wire format, Protobuf supports a canonical encoding in [JSON](/programming-guides/json). ## Options {#options} @@ -1554,19 +1553,18 @@ Here are a few of the most commonly used options: `LITE_RUNTIME`. This affects the C++ and Java code generators (and possibly third-party generators) in the following ways: - * `SPEED` (default): The protocol buffer compiler will generate code for + * `SPEED` (default): The Protobuf compiler will generate code for serializing, parsing, and performing other common operations on your 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 - 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 - blindingly fast. - * `LITE_RUNTIME`: The protocol buffer compiler will generate classes that - depend only on the "lite" runtime library (`libprotobuf-lite` instead of + * `CODE_SIZE`: The Protobuf compiler will generate minimal classes and + will rely on shared, reflection-based code to implement 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 blindingly fast. + * `LITE_RUNTIME`: The Protobuf compiler will generate classes that depend + only on the "lite" runtime library (`libprotobuf-lite` instead of `libprotobuf`). The lite runtime is much smaller than the full library (around an order of magnitude smaller) but omits certain features like descriptors and reflection. This is particularly useful for apps running @@ -1665,9 +1663,9 @@ values and to fields. ### Custom Options {#customoptions} -Protocol Buffers also allows you to define and use your own options. Note that -this is an **advanced feature** which most people don't need. If you do think -you need to create your own options, see the +Protobuf also allows you to define and use your own options. Note that this is +an **advanced feature** which most people don't need. If you do think you need +to create your own options, see the [Proto2 Language Guide](/programming-guides/proto2#customoptions) for details. Note that creating custom options uses [extensions](/programming-guides/proto2#extensions), @@ -1712,10 +1710,10 @@ since it is the default behavior. When a message field is marked override that by trying to set `RETENTION_RUNTIME`. {{% alert title="Note" color="note" %}} As -of Protocol Buffers 22.0, support for option retention is still in progress and -only C++ and Java are supported. Go has support starting from 1.29.0. Python -support is complete but has not made it into a release yet. -{{% /alert %}} +of Protobuf 22.0, support for option retention is still in progress and only C++ +and Java are supported. Go has support starting from 1.29.0. Python support is +complete but has not made it into a release +yet. {{% /alert %}} ### Option Targets {#option-targets} @@ -1770,15 +1768,15 @@ enum MyEnum { To generate the Java, Kotlin, Python, C++, Go, Ruby, Objective-C, or C# code that you need to work with the message types defined in a `.proto` file, you -need to run the protocol buffer compiler `protoc` on the `.proto` file. If you -haven't installed the compiler, +need to run the Protobuf compiler `protoc` on the `.proto` file. If you haven't +installed the compiler, [download the package](/downloads) and follow the instructions in the README. For Go, you also need to install a special code generator plugin for the compiler; you can find this and installation instructions in the [golang/protobuf](https://github.com/golang/protobuf/) repository on GitHub. -The protobuf compiler is invoked as follows: +The Protobuf compiler is invoked as follows: ```sh protoc --proto_path=IMPORT_PATH --cpp_out=DST_DIR --java_out=DST_DIR --python_out=DST_DIR --go_out=DST_DIR --ruby_out=DST_DIR --objc_out=DST_DIR --csharp_out=DST_DIR path/to/file.proto diff --git a/content/programming-guides/serialization-not-canonical.md b/content/programming-guides/serialization-not-canonical.md index 3bc655c28..34a14dd69 100644 --- a/content/programming-guides/serialization-not-canonical.md +++ b/content/programming-guides/serialization-not-canonical.md @@ -17,7 +17,7 @@ that proto. Use cases include: * taking a fingerprint or checksum of a serialized proto * comparing serialized payloads as a way of checking message equality -Unfortunately, *protobuf serialization is not (and cannot be) canonical*. There +Unfortunately, *Protobuf serialization is not (and cannot be) canonical*. There are a few notable exceptions, such as MapReduce, but in general you should generally think of proto serialization as unstable. This page explains why. @@ -61,10 +61,10 @@ Deterministic serialization is not canonical. The serializer can generate different output for many reasons, including but not limited to the following variations: -1. The protobuf schema changes in any way. +1. The Protobuf schema changes in any way. 1. The application being built changes in any way. 1. The binary is built with different flags (eg. opt vs. debug). -1. The protobuf library is updated. +1. The Protobuf library is updated. This means that hashes of serialized protos are fragile and not stable across time or space. diff --git a/content/programming-guides/style.md b/content/programming-guides/style.md index 9406632cc..dd082ba7d 100644 --- a/content/programming-guides/style.md +++ b/content/programming-guides/style.md @@ -6,7 +6,7 @@ type = "docs" +++ This document provides a style guide for `.proto` files. By following these -conventions, you'll make your protocol buffer message definitions and their +conventions, you'll make your Protobuf message definitions and their corresponding classes consistent and easy to read. Enforcement of the following style guidelines is controlled via @@ -65,7 +65,7 @@ Don't use underscores as the initial or final character of a name. Any underscore should always be followed by a letter (not a number or a second underscore). -The motivation for this rule is that each protobuf language implementation may +The motivation for this rule is that each Protobuf language implementation may convert identifiers into the local language style: a name of `song_id` in a .proto file may end up having accessors for the field which are capitalized as `SongId`, `songId` or `song_id` depending on the language. @@ -315,7 +315,7 @@ removed in proto3. Proto2 `required` fields that have been migrated to editions accommodate. While enforcement of required fields at the schema level is intuitively -desirable, one of the primary design goals of protobuf is to support long term +desirable, one of the primary design goals of Protobuf is to support long term schema evolution. No matter how obviously required a given field seems to be today, there is a plausible future where the field should no longer be set (e.g. an `int64 user_id` may need to migrate to a `UserId user_id` in the future). diff --git a/content/programming-guides/techniques.md b/content/programming-guides/techniques.md index f192008e2..f91ff659d 100644 --- a/content/programming-guides/techniques.md +++ b/content/programming-guides/techniques.md @@ -1,13 +1,12 @@ +++ title = "Techniques" weight = 70 -description = "Describes some commonly-used design patterns for dealing with Protocol Buffers." +description = "Describes some commonly-used design patterns for dealing with Protobuf." type = "docs" +++ You can also send design and usage questions to -the -[Protocol Buffers discussion group](http://groups.google.com/group/protobuf). +the [Protobuf discussion group](http://groups.google.com/group/protobuf). ## Common Filename Suffixes {#suffixes} @@ -26,30 +25,29 @@ recommend `.txtpb` for its brevity. ## Streaming Multiple Messages {#streaming} If you want to write multiple messages to a single file or stream, it is up to -you to keep track of where one message ends and the next begins. The Protocol -Buffer wire format is not self-delimiting, so protocol buffer parsers cannot -determine where a message ends on their own. The easiest way to solve this -problem is to write the size of each message before you write the message -itself. When you read the messages back in, you read the size, then read the -bytes into a separate buffer, then parse from that buffer. (If you want to avoid -copying bytes to a separate buffer, check out the `CodedInputStream` class (in -both C++ and Java) which can be told to limit reads to a certain number of -bytes.) +you to keep track of where one message ends and the next begins. The Protobuf +wire format is not self-delimiting, so Protobuf parsers cannot determine where a +message ends on their own. The easiest way to solve this problem is to write the +size of each message before you write the message itself. When you read the +messages back in, you read the size, then read the bytes into a separate buffer, +then parse from that buffer. (If you want to avoid copying bytes to a separate +buffer, check out the `CodedInputStream` class (in both C++ and Java) which can +be told to limit reads to a certain number of bytes.) ## Large Data Sets {#large-data} -Protocol Buffers are not designed to handle large messages. As a general rule of -thumb, if you are dealing in messages larger than a megabyte each, it may be -time to consider an alternate strategy. +Protobuf is not designed to handle large messages. As a general rule of thumb, +if you are dealing in messages larger than a megabyte each, it may be time to +consider an alternate strategy. -That said, Protocol Buffers are great for handling individual messages *within* -a large data set. Usually, large data sets are a collection of small pieces, -where each small piece is structured data. Even though Protocol Buffers cannot -handle the entire set at once, using Protocol Buffers to encode each piece -greatly simplifies your problem: now all you need is to handle a set of byte -strings rather than a set of structures. +That said, Protobuf is great for handling individual messages *within* a large +data set. Usually, large data sets are a collection of small pieces, where each +small piece is structured data. Even though Protobuf cannot handle the entire +set at once, using Protobuf to encode each piece greatly simplifies your +problem: now all you need is to handle a set of byte strings rather than a set +of structures. -Protocol Buffers do not include any built-in support for large data sets because +Protobuf does not include any built-in support for large data sets because different situations call for different solutions. Sometimes a simple list of records will do while other times you want something more like a database. Each solution should be developed as a separate library, so that only those who need @@ -57,13 +55,13 @@ it need pay the costs. ## Self-describing Messages {#self-description} -Protocol Buffers do not contain descriptions of their own types. Thus, given +Protobuf messages do not contain descriptions of their own types. Thus, given only a raw message without the corresponding `.proto` file defining its type, it is difficult to extract any useful data. -However, the contents of a .proto file can itself be represented using protocol -buffers. The file `src/google/protobuf/descriptor.proto` in the source code -package defines the message types involved. `protoc` can output a +However, the contents of a .proto file can itself be represented using Protobuf. +The file `src/google/protobuf/descriptor.proto` in the source code package +defines the message types involved. `protoc` can output a `FileDescriptorSet`—which represents a set of .proto files—using the `--descriptor_set_out` option. With this, you can define a self-describing protocol message like so: @@ -87,7 +85,7 @@ By using classes like `DynamicMessage` (available in C++ and Java), you can then write tools which can manipulate `SelfDescribingMessage`s. All that said, the reason that this functionality is not included in the -Protocol Buffer library is because we have never had a use for it inside Google. +Protobuf library is because we have never had a use for it inside Google. This technique requires support for dynamic messages using descriptors. Check that your platforms support this feature before using self-describing messages. diff --git a/content/reference/_index.md b/content/reference/_index.md index ccfc64524..196b4d836 100644 --- a/content/reference/_index.md +++ b/content/reference/_index.md @@ -1,17 +1,17 @@ +++ title = "Reference Guides" weight = 490 -description = "Reference documentation for working with protocol buffer classes in C++, Java, Python, Go, C#, Objective-C, Ruby, PHP, and Dart, as well as some reference documentation for Protocol Buffers itself." +description = "Reference documentation for working with Protobuf classes in C++, Java, Python, Go, C#, Objective-C, Ruby, PHP, and Dart, as well as some reference documentation for Protobuf itself." type = "docs" +++ -This section contains reference documentation for working with protocol buffer -classes in C++, Java, Python, Go, C\#, Objective-C, Ruby, PHP, and Dart, as well -as some reference documentation for Protocol Buffers itself. The documentation -for each language includes (where available): +This section contains reference documentation for working with Protobuf classes +in C++, Java, Python, Go, C\#, Objective-C, Ruby, PHP, and Dart, as well as some +reference documentation for Protobuf itself. The documentation for each language +includes (where available): -- A reference guide to the code generated by the protocol buffer compiler from - your `.proto` files. +- A reference guide to the code generated by the Protobuf compiler from your + `.proto` files. - Generated API documentation for the provided source code. Note that there are APIs for several more languages in the pipeline -- for diff --git a/content/reference/cpp/_index.md b/content/reference/cpp/_index.md index 0321844c5..6f2d26890 100644 --- a/content/reference/cpp/_index.md +++ b/content/reference/cpp/_index.md @@ -2,6 +2,6 @@ title = "C++ Reference" weight = 500 linkTitle = "C++" -description = "Reference documentation for working with protocol buffer classes in C++." +description = "Reference documentation for working with Protobuf classes in C++." type = "docs" +++ diff --git a/content/reference/cpp/abseil.md b/content/reference/cpp/abseil.md index 63cb44641..d75764c09 100644 --- a/content/reference/cpp/abseil.md +++ b/content/reference/cpp/abseil.md @@ -2,16 +2,16 @@ title = "Abseil Support" weight = 530 linkTitle = "Abseil Support" -description = "The C++ implementation of Protocol Buffers has an explicit dependency on Abseil." +description = "The C++ implementation of Protobuf has an explicit dependency on Abseil." type = "docs" +++ -In [version 22.x](/news/v22#abseil-dep), C++ protobuf +In [version 22.x](/news/v22#abseil-dep), C++ Protobuf added an explicit dependency on Abseil. ## Bazel Support {#bazel} -If you are using Bazel, to determine the version of Abseil that your protobuf +If you are using Bazel, to determine the version of Abseil that your Protobuf version supports, you can use the `bazel mod` command: ```shell diff --git a/content/reference/cpp/api-docs/_index.md b/content/reference/cpp/api-docs/_index.md index d049869b0..4fa254611 100644 --- a/content/reference/cpp/api-docs/_index.md +++ b/content/reference/cpp/api-docs/_index.md @@ -4,13 +4,13 @@ title = "C++ Reference" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ -

    Packages

    Auxiliary classes used for I/O.
    Utility classes.
    Implementation of the Protocol Buffer compiler.

    google::protobuf

    Files

    This file defines an Arena allocator for better allocation performance.
    This file contains classes which describe a type of protocol message.
    Protocol buffer representations of descriptors.
    Interface for manipulating databases of descriptors.
    Defines an implementation of Message which can emulate types which are not known at compile-time.
    This file defines the map container and its helpers to support protobuf maps.
    Defines Message, the abstract interface implemented by non-lite protocol message objects.
    Defines MessageLite, the abstract interface implemented by all (lite and non-lite) protocol message objects.
    RepeatedField and RepeatedPtrField are used by generated protocol message classes to manipulate repeated fields.
    DEPRECATED: This module declares the abstract interfaces underlying proto2 RPC services.
    Utilities for printing and parsing protocol messages in a human-readable, text-based format.
    Contains classes used to keep track of unrecognized fields seen while parsing a protocol message.

    google::protobuf::io

    Auxiliary classes used for I/O.

    The Protocol Buffer library uses the classes in this package to deal with I/O and encoding/decoding raw bytes. Most users will not need to deal with this package. However, users who want to adapt the system to work with their own I/O abstractions – e.g., to allow Protocol Buffers to be read from a different kind of input stream without the need for a temporary buffer – should take a closer look.

    -

    Files

    This file contains the CodedInputStream and CodedOutputStream classes, which wrap a ZeroCopyInputStream or ZeroCopyOutputStream, respectively, and allow you to read or write individual pieces of data in various formats.
    Utility class for writing text to a ZeroCopyOutputStream.
    Class for parsing tokenized text from a ZeroCopyInputStream.
    This file contains the ZeroCopyInputStream and ZeroCopyOutputStream interfaces, which represent abstract I/O streams to and from which protocol buffers can be read and written.
    This file contains common implementations of the interfaces defined in zero_copy_stream.h which are only included in the full (non-lite) protobuf library.
    This file contains common implementations of the interfaces defined in zero_copy_stream.h which are included in the "lite" protobuf library.

    google::protobuf::util

    Utility classes.

    This package contains various utilities for message comparison, JSON conversion, well known types, etc.

    -

    Files

    Defines classes for field comparison.
    Defines utilities for the FieldMask well known type.
    Utility functions to convert between protobuf binary format and proto3 JSON format.
    This file defines static methods and classes for comparing Protocol Messages.
    Defines utilities for the Timestamp and Duration well known types.
    Defines a TypeResolver for the Any message.
    Defines utilities for the TypeResolver.

    google::protobuf::compiler

    Implementation of the Protocol Buffer compiler.

    This package contains code for parsing .proto files and generating code based on them. There are two reasons you might be interested in this package:

    +

    Packages

    Auxiliary classes used for I/O.
    Utility classes.
    Implementation of the Protobuf compiler.

    google::protobuf

    Files

    This file defines an Arena allocator for better allocation performance.
    This file contains classes which describe a type of protocol message.
    Protobuf representations of descriptors.
    Interface for manipulating databases of descriptors.
    Defines an implementation of Message which can emulate types which are not known at compile-time.
    This file defines the map container and its helpers to support Protobuf maps.
    Defines Message, the abstract interface implemented by non-lite protocol message objects.
    Defines MessageLite, the abstract interface implemented by all (lite and non-lite) protocol message objects.
    RepeatedField and RepeatedPtrField are used by generated protocol message classes to manipulate repeated fields.
    DEPRECATED: This module declares the abstract interfaces underlying proto2 RPC services.
    Utilities for printing and parsing protocol messages in a human-readable, text-based format.
    Contains classes used to keep track of unrecognized fields seen while parsing a protocol message.

    google::protobuf::io

    Auxiliary classes used for I/O.

    The Protobuf library uses the classes in this package to deal with I/O and encoding/decoding raw bytes. Most users will not need to deal with this package. However, users who want to adapt the system to work with their own I/O abstractions – e.g., to allow Protobuf messages to be read from a different kind of input stream without the need for a temporary buffer – should take a closer look.

    +

    Files

    This file contains the CodedInputStream and CodedOutputStream classes, which wrap a ZeroCopyInputStream or ZeroCopyOutputStream, respectively, and allow you to read or write individual pieces of data in various formats.
    Utility class for writing text to a ZeroCopyOutputStream.
    Class for parsing tokenized text from a ZeroCopyInputStream.
    This file contains the ZeroCopyInputStream and ZeroCopyOutputStream interfaces, which represent abstract I/O streams to and from which Protobuf messages can be read and written.
    This file contains common implementations of the interfaces defined in zero_copy_stream.h which are only included in the full (non-lite) Protobuf library.
    This file contains common implementations of the interfaces defined in zero_copy_stream.h which are included in the "lite" Protobuf library.

    google::protobuf::util

    Utility classes.

    This package contains various utilities for message comparison, JSON conversion, well known types, etc.

    +

    Files

    Defines classes for field comparison.
    Defines utilities for the FieldMask well known type.
    Utility functions to convert between Protobuf binary format and proto3 JSON format.
    This file defines static methods and classes for comparing Protocol Messages.
    Defines utilities for the Timestamp and Duration well known types.
    Defines a TypeResolver for the Any message.
    Defines utilities for the TypeResolver.

    google::protobuf::compiler

    Implementation of the Protobuf compiler.

    This package contains code for parsing .proto files and generating code based on them. There are two reasons you might be interested in this package:

    • You want to parse .proto files at runtime. In this case, you should look at importer.h. Since this functionality is widely useful, it is included in the libprotobuf base library; you do not have to link against libprotoc.
    • You want to write a custom protocol compiler which generates different kinds of code, e.g. code in a different language which is not supported by the official compiler. For this purpose, command_line_interface.h provides you with a complete compiler front-end, so all you need to do is write a custom implementation of CodeGenerator and a trivial main() function. You can even make your compiler support the official languages in addition to your own. Since this functionality is only useful to those writing custom compilers, it is in a separate library called "libprotoc" which you will have to link against.
      • diff --git a/content/reference/cpp/api-docs/google.protobuf.arena.md b/content/reference/cpp/api-docs/google.protobuf.arena.md index de2992881..bd09ff282 100644 --- a/content/reference/cpp/api-docs/google.protobuf.arena.md +++ b/content/reference/cpp/api-docs/google.protobuf.arena.md @@ -4,7 +4,7 @@ title = "arena.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ @@ -29,7 +29,7 @@ type = "docs"
    • The type T may have the type trait |DestructorSkippable_|. If this type trait is present in the type, then its destructor will not be called if and only if it was passed a non-NULL arena pointer. If this type trait is not present on the type, then its destructor is always called when the containing arena is destroyed.
    -

    This protocol is implemented by all arena-enabled proto2 message classes as well as protobuf container types like RepeatedPtrField and Map. The protocol is internal to protobuf and is not guaranteed to be stable. Non-proto types should not rely on this protocol.

    +

    This protocol is implemented by all arena-enabled proto2 message classes as well as Protobuf container types like RepeatedPtrField and Map. The protocol is internal to Protobuf and is not guaranteed to be stable. Non-proto types should not rely on this protocol.

    Members

    const size_t
    kBlockOverhead = = internal::ThreadSafeArena::kBlockHeaderSize + diff --git a/content/reference/cpp/api-docs/google.protobuf.common.md b/content/reference/cpp/api-docs/google.protobuf.common.md index abd2f99d7..767097fe7 100644 --- a/content/reference/cpp/api-docs/google.protobuf.common.md +++ b/content/reference/cpp/api-docs/google.protobuf.common.md @@ -2,7 +2,7 @@ title = "common.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.code_generator.md b/content/reference/cpp/api-docs/google.protobuf.compiler.code_generator.md index 9ca8ebba6..7ba7e5509 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.code_generator.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.code_generator.md @@ -2,7 +2,7 @@ title = "code_generator.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ @@ -12,13 +12,13 @@ type = "docs" 
    ("foo", "bar"), ("baz", ""), ("qux", "corge")

    class CodeGenerator

    #include <google/protobuf/compiler/code_generator.h>
    namespace google::protobuf::compiler

    The abstract interface to a class which generates code implementing a particular proto file in a particular language.

    A number of these may be registered with CommandLineInterface to support various languages.

    -

    Known subclasses:

    Members

    enum
    Feature
    Sync with plugin.proto. more...
    CodeGenerator()
    virtual
    ~CodeGenerator()
    virtual bool
    Generate(const FileDescriptor * file, const std::string & parameter, GeneratorContext * generator_context, std::string * error) const = 0
    Generates code for the given proto file, generating one or more files in the given output directory. more...
    virtual bool
    GenerateAll(const std::vector< const FileDescriptor * > & files, const std::string & parameter, GeneratorContext * generator_context, std::string * error) const
    Generates code for all given proto files. more...
    virtual uint64_t
    GetSupportedFeatures() const
    Implement this to indicate what features this code generator supports. more...
    virtual bool
    HasGenerateAll() const
    This is no longer used, but this class is part of the opensource protobuf library, so it has to remain to keep vtables the same for the current version of the library. more...

    enum CodeGenerator::Feature {
      FEATURE_PROTO3_OPTIONAL = = 1
    }

    Sync with plugin.proto.

    FEATURE_PROTO3_OPTIONAL

    virtual bool CodeGenerator::Generate(
            const FileDescriptor * file,
            const std::string & parameter,
            GeneratorContext * generator_context,
            std::string * error) const = 0

    Generates code for the given proto file, generating one or more files in the given output directory.

    A parameter to be passed to the generator can be specified on the command line. This is intended to be used to pass generator specific parameters. It is empty if no parameter was given. ParseGeneratorParameter (below), can be used to accept multiple parameters within the single parameter command line flag.

    +

    Known subclasses:

    Members

    enum
    Feature
    Sync with plugin.proto. more...
    CodeGenerator()
    virtual
    ~CodeGenerator()
    virtual bool
    Generate(const FileDescriptor * file, const std::string & parameter, GeneratorContext * generator_context, std::string * error) const = 0
    Generates code for the given proto file, generating one or more files in the given output directory. more...
    virtual bool
    GenerateAll(const std::vector< const FileDescriptor * > & files, const std::string & parameter, GeneratorContext * generator_context, std::string * error) const
    Generates code for all given proto files. more...
    virtual uint64_t
    GetSupportedFeatures() const
    Implement this to indicate what features this code generator supports. more...
    virtual bool
    HasGenerateAll() const
    This is no longer used, but this class is part of the open-source Protobuf library, so it has to remain to keep vtables the same for the current version of the library. more...

    enum CodeGenerator::Feature {
      FEATURE_PROTO3_OPTIONAL = = 1
    }

    Sync with plugin.proto.

    FEATURE_PROTO3_OPTIONAL

    virtual bool CodeGenerator::Generate(
            const FileDescriptor * file,
            const std::string & parameter,
            GeneratorContext * generator_context,
            std::string * error) const = 0

    Generates code for the given proto file, generating one or more files in the given output directory.

    A parameter to be passed to the generator can be specified on the command line. This is intended to be used to pass generator specific parameters. It is empty if no parameter was given. ParseGeneratorParameter (below), can be used to accept multiple parameters within the single parameter command line flag.

    Returns true if successful. Otherwise, sets *error to a description of the problem (e.g. "invalid parameter") and returns false.

    virtual bool CodeGenerator::GenerateAll(
            const std::vector< const FileDescriptor * > & files,
            const std::string & parameter,
            GeneratorContext * generator_context,
            std::string * error) const

    Generates code for all given proto files.

    WARNING: The canonical code generator design produces one or two output files per input .proto file, and we do not wish to encourage alternate designs.

    A parameter is given as passed on the command line, as in |Generate()| above.

    Returns true if successful. Otherwise, sets *error to a description of the problem (e.g. "invalid parameter") and returns false.

    virtual uint64_t CodeGenerator::GetSupportedFeatures() const

    Implement this to indicate what features this code generator supports.

    This should be a bitwise OR of features from the Features enum in plugin.proto.

    -

    virtual bool CodeGenerator::HasGenerateAll() const

    This is no longer used, but this class is part of the opensource protobuf library, so it has to remain to keep vtables the same for the current version of the library.

    When protobufs does a api breaking change, the method can be removed.

    +

    virtual bool CodeGenerator::HasGenerateAll() const

    This is no longer used, but this class is part of the open-source Protobuf library, so it has to remain to keep vtables the same for the current version of the library.

    When Protobuf does an API breaking change, the method can be removed.

    class GeneratorContext

    #include <google/protobuf/compiler/code_generator.h>
    namespace google::protobuf::compiler

    CodeGenerators generate one or more files in a given directory.

    This abstract interface represents the directory to which the CodeGenerator is to write and other information about the context in which the Generator runs.

    Members

    GeneratorContext()
    virtual
    ~GeneratorContext()
    virtual io::ZeroCopyOutputStream *
    Open(const std::string & filename) = 0
    Opens the given file, truncating it if it exists, and returns a ZeroCopyOutputStream that writes to the file. more...
    virtual io::ZeroCopyOutputStream *
    OpenForAppend(const std::string & filename)
    Similar to Open() but the output will be appended to the file if exists.
    virtual io::ZeroCopyOutputStream *
    OpenForInsert(const std::string & filename, const std::string & insertion_point)
    Creates a ZeroCopyOutputStream which will insert code into the given file at the given insertion point. more...
    virtual io::ZeroCopyOutputStream *
    OpenForInsertWithGeneratedCodeInfo(const std::string & filename, const std::string & insertion_point, const google::protobuf::GeneratedCodeInfo & info)
    Similar to OpenForInsert, but if info is non-empty, will open (or create) filename.pb.meta and insert info at the appropriate place with the necessary shifts. more...
    virtual void
    ListParsedFiles(std::vector< const FileDescriptor * > * output)
    Returns a vector of FileDescriptors for all the files being compiled in this run. more...
    virtual void
    GetCompilerVersion(Version * version) const
    Retrieves the version number of the protocol compiler associated with this GeneratorContext.

    virtual io::ZeroCopyOutputStream *
        GeneratorContext::Open(
            const std::string & filename) = 0

    Opens the given file, truncating it if it exists, and returns a ZeroCopyOutputStream that writes to the file.

    The caller takes ownership of the returned object. This method never fails (a dummy stream will be returned instead).

    The filename given should be relative to the root of the source tree. E.g. the C++ generator, when generating code for "foo/bar.proto", will generate the files "foo/bar.pb.h" and "foo/bar.pb.cc"; note that "foo/" is included in these filenames. The filename is not allowed to contain "." or ".." components.

    diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.command_line_interface.md b/content/reference/cpp/api-docs/google.protobuf.compiler.command_line_interface.md index 0dbfe78ed..185026ecd 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.command_line_interface.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.command_line_interface.md @@ -2,7 +2,7 @@ title = "command_line_interface.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.cpp_generator.md b/content/reference/cpp/api-docs/google.protobuf.compiler.cpp_generator.md index d29feb4f1..48672e93b 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.cpp_generator.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.cpp_generator.md @@ -2,7 +2,7 @@ title = "cpp_generator.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.csharp_generator.md b/content/reference/cpp/api-docs/google.protobuf.compiler.csharp_generator.md index 86881202d..bfe0bb7d0 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.csharp_generator.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.csharp_generator.md @@ -2,7 +2,7 @@ title = "csharp_generator.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.csharp_names.md b/content/reference/cpp/api-docs/google.protobuf.compiler.csharp_names.md index 529e48e62..081550685 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.csharp_names.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.csharp_names.md @@ -2,7 +2,7 @@ title = "csharp_names.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.importer.md b/content/reference/cpp/api-docs/google.protobuf.compiler.importer.md index 2df4c25fa..1804ffea0 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.importer.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.importer.md @@ -2,7 +2,7 @@ title = "importer.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.java_generator.md b/content/reference/cpp/api-docs/google.protobuf.compiler.java_generator.md index 98c6536a4..9ca74e12d 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.java_generator.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.java_generator.md @@ -2,7 +2,7 @@ title = "java_generator.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.java_names.md b/content/reference/cpp/api-docs/google.protobuf.compiler.java_names.md index 9a1103b96..f8b33d871 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.java_names.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.java_names.md @@ -2,7 +2,7 @@ title = "java_names.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.javanano_generator.md b/content/reference/cpp/api-docs/google.protobuf.compiler.javanano_generator.md index 7ec4bac30..a293ed869 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.javanano_generator.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.javanano_generator.md @@ -2,7 +2,7 @@ title = "javanano_generator.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.js_generator.md b/content/reference/cpp/api-docs/google.protobuf.compiler.js_generator.md index 2fc00b01b..6ab34ccb5 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.js_generator.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.js_generator.md @@ -2,7 +2,7 @@ title = "js_generator.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ @@ -10,9 +10,9 @@ type = "docs"

    bool GeneratorOptions::annotate_code

    If true, we should append annotations as comments on the last line for generated .js file.

    Annotations used by tools like to provide cross-references between .js and .proto files. Annotations are encoded as base64 proto of GeneratedCodeInfo message (see descriptor.proto).

    class Generator: public CodeGenerator

    #include <google/protobuf/compiler/js/js_generator.h>
    namespace google::protobuf::compiler::js

    CodeGenerator implementation which generates a JavaScript source file and header.

    If you create your own protocol compiler binary and you want it to support JavaScript output, you can do so by registering an instance of this CodeGenerator with the CommandLineInterface in your main() function.

    -

    Members

    Generator()
    virtual
    ~Generator()
    virtual bool
    Generate(const FileDescriptor * file, const std::string & parameter, GeneratorContext * generator_context, std::string * error) const
    Generates code for the given proto file, generating one or more files in the given output directory. more...
    virtual bool
    HasGenerateAll() const
    This is no longer used, but this class is part of the opensource protobuf library, so it has to remain to keep vtables the same for the current version of the library. more...
    virtual bool
    GenerateAll(const std::vector< const FileDescriptor * > & files, const std::string & parameter, GeneratorContext * generator_context, std::string * error) const
    Generates code for all given proto files. more...
    virtual uint64
    GetSupportedFeatures() const
    Implement this to indicate what features this code generator supports. more...

    virtual bool Generator::Generate(
            const FileDescriptor * file,
            const std::string & parameter,
            GeneratorContext * generator_context,
            std::string * error) const

    Generates code for the given proto file, generating one or more files in the given output directory.

    A parameter to be passed to the generator can be specified on the command line. This is intended to be used to pass generator specific parameters. It is empty if no parameter was given. ParseGeneratorParameter (below), can be used to accept multiple parameters within the single parameter command line flag.

    +

    Members

    Generator()
    virtual
    ~Generator()
    virtual bool
    Generate(const FileDescriptor * file, const std::string & parameter, GeneratorContext * generator_context, std::string * error) const
    Generates code for the given proto file, generating one or more files in the given output directory. more...
    virtual bool
    HasGenerateAll() const
    This is no longer used, but this class is part of the open-source Protobuf library, so it has to remain to keep vtables the same for the current version of the library. more...
    virtual bool
    GenerateAll(const std::vector< const FileDescriptor * > & files, const std::string & parameter, GeneratorContext * generator_context, std::string * error) const
    Generates code for all given proto files. more...
    virtual uint64
    GetSupportedFeatures() const
    Implement this to indicate what features this code generator supports. more...

    virtual bool Generator::Generate(
            const FileDescriptor * file,
            const std::string & parameter,
            GeneratorContext * generator_context,
            std::string * error) const

    Generates code for the given proto file, generating one or more files in the given output directory.

    A parameter to be passed to the generator can be specified on the command line. This is intended to be used to pass generator specific parameters. It is empty if no parameter was given. ParseGeneratorParameter (below), can be used to accept multiple parameters within the single parameter command line flag.

    Returns true if successful. Otherwise, sets *error to a description of the problem (e.g. "invalid parameter") and returns false.

    -

    virtual bool Generator::HasGenerateAll() const

    This is no longer used, but this class is part of the opensource protobuf library, so it has to remain to keep vtables the same for the current version of the library.

    When protobufs does a api breaking change, the method can be removed.

    +

    virtual bool Generator::HasGenerateAll() const

    This is no longer used, but this class is part of the open-source Protobuf library, so it has to remain to keep vtables the same for the current version of the library.

    When Protobuf does an API breaking change, the method can be removed.

    virtual bool Generator::GenerateAll(
            const std::vector< const FileDescriptor * > & files,
            const std::string & parameter,
            GeneratorContext * generator_context,
            std::string * error) const

    Generates code for all given proto files.

    WARNING: The canonical code generator design produces one or two output files per input .proto file, and we do not wish to encourage alternate designs.

    A parameter is given as passed on the command line, as in |Generate()| above.

    Returns true if successful. Otherwise, sets *error to a description of the problem (e.g. "invalid parameter") and returns false.

    diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.objectivec_generator.md b/content/reference/cpp/api-docs/google.protobuf.compiler.objectivec_generator.md index ad236a33c..e994ce5b6 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.objectivec_generator.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.objectivec_generator.md @@ -2,13 +2,13 @@ title = "objectivec_generator.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++

    #include <google/protobuf/compiler/objectivec/objectivec_generator.h>
    namespace google::protobuf::compiler::objectivec

    Generates ObjectiveC code for a given .proto file.

    Classes in this file

    CodeGenerator implementation which generates a ObjectiveC source file and header.

    class ObjectiveCGenerator: public CodeGenerator

    #include <google/protobuf/compiler/objectivec/objectivec_generator.h>
    namespace google::protobuf::compiler::objectivec

    CodeGenerator implementation which generates a ObjectiveC source file and header.

    If you create your own protocol compiler binary and you want it to support ObjectiveC output, you can do so by registering an instance of this CodeGenerator with the CommandLineInterface in your main() function.

    -

    Members

    ObjectiveCGenerator()
    ~ObjectiveCGenerator()
    ObjectiveCGenerator(const ObjectiveCGenerator & )
    ObjectiveCGenerator &
    operator=(const ObjectiveCGenerator & )

    implements CodeGenerator

    virtual bool
    HasGenerateAll() const
    This is no longer used, but this class is part of the opensource protobuf library, so it has to remain to keep vtables the same for the current version of the library. more...
    virtual bool
    Generate(const FileDescriptor * file, const std::string & parameter, GeneratorContext * generator_context, std::string * error) const
    Generates code for the given proto file, generating one or more files in the given output directory. more...
    virtual bool
    GenerateAll(const std::vector< const FileDescriptor * > & files, const std::string & parameter, GeneratorContext * generator_context, std::string * error) const
    Generates code for all given proto files. more...
    virtual uint64_t
    GetSupportedFeatures() const
    Implement this to indicate what features this code generator supports. more...

    virtual bool ObjectiveCGenerator::HasGenerateAll() const

    This is no longer used, but this class is part of the opensource protobuf library, so it has to remain to keep vtables the same for the current version of the library.

    When protobufs does a api breaking change, the method can be removed.

    +

    Members

    ObjectiveCGenerator()
    ~ObjectiveCGenerator()
    ObjectiveCGenerator(const ObjectiveCGenerator & )
    ObjectiveCGenerator &
    operator=(const ObjectiveCGenerator & )

    implements CodeGenerator

    virtual bool
    HasGenerateAll() const
    This is no longer used, but this class is part of the open-source Protobuf library, so it has to remain to keep vtables the same for the current version of the library. more...
    virtual bool
    Generate(const FileDescriptor * file, const std::string & parameter, GeneratorContext * generator_context, std::string * error) const
    Generates code for the given proto file, generating one or more files in the given output directory. more...
    virtual bool
    GenerateAll(const std::vector< const FileDescriptor * > & files, const std::string & parameter, GeneratorContext * generator_context, std::string * error) const
    Generates code for all given proto files. more...
    virtual uint64_t
    GetSupportedFeatures() const
    Implement this to indicate what features this code generator supports. more...

    virtual bool ObjectiveCGenerator::HasGenerateAll() const

    This is no longer used, but this class is part of the open-source Protobuf library, so it has to remain to keep vtables the same for the current version of the library.

    When Protobuf does an API breaking change, the method can be removed.

    virtual bool ObjectiveCGenerator::Generate(
            const FileDescriptor * file,
            const std::string & parameter,
            GeneratorContext * generator_context,
            std::string * error) const

    Generates code for the given proto file, generating one or more files in the given output directory.

    A parameter to be passed to the generator can be specified on the command line. This is intended to be used to pass generator specific parameters. It is empty if no parameter was given. ParseGeneratorParameter (below), can be used to accept multiple parameters within the single parameter command line flag.

    Returns true if successful. Otherwise, sets *error to a description of the problem (e.g. "invalid parameter") and returns false.

    virtual bool ObjectiveCGenerator::GenerateAll(
            const std::vector< const FileDescriptor * > & files,
            const std::string & parameter,
            GeneratorContext * generator_context,
            std::string * error) const

    Generates code for all given proto files.

    WARNING: The canonical code generator design produces one or two output files per input .proto file, and we do not wish to encourage alternate designs.

    diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.objectivec_helpers.md b/content/reference/cpp/api-docs/google.protobuf.compiler.objectivec_helpers.md index ba401a92f..07557d4f4 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.objectivec_helpers.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.objectivec_helpers.md @@ -2,7 +2,7 @@ title = "objectivec_helpers.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.parser.md b/content/reference/cpp/api-docs/google.protobuf.compiler.parser.md index cba5c8eda..17de7af27 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.parser.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.parser.md @@ -2,7 +2,7 @@ title = "parser.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.plugin.md b/content/reference/cpp/api-docs/google.protobuf.compiler.plugin.md index 6e69a5124..61bc007fc 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.plugin.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.plugin.md @@ -2,7 +2,7 @@ title = "plugin.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.plugin.pb.md b/content/reference/cpp/api-docs/google.protobuf.compiler.plugin.pb.md index 77771358d..37ce54093 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.plugin.pb.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.plugin.pb.md @@ -2,7 +2,7 @@ title = "plugin.pb.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.python_generator.md b/content/reference/cpp/api-docs/google.protobuf.compiler.python_generator.md index a87811668..d8cad39d2 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.python_generator.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.python_generator.md @@ -2,11 +2,11 @@ title = "python_generator.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ -

    #include <google/protobuf/compiler/python/python_generator.h>
    namespace google::protobuf::compiler::python

    Generates Python code for a given .proto file.

    Classes in this file

    CodeGenerator implementation for generated Python protocol buffer classes.

    class Generator: public CodeGenerator

    #include <google/protobuf/compiler/python/python_generator.h>
    namespace google::protobuf::compiler::python

    CodeGenerator implementation for generated Python protocol buffer classes.

    If you create your own protocol compiler binary and you want it to support Python output, you can do so by registering an instance of this CodeGenerator with the CommandLineInterface in your main() function.

    +

    #include <google/protobuf/compiler/python/python_generator.h>
    namespace google::protobuf::compiler::python

    Generates Python code for a given .proto file.

    Classes in this file

    CodeGenerator implementation for generated Python Protobuf classes.

    class Generator: public CodeGenerator

    #include <google/protobuf/compiler/python/python_generator.h>
    namespace google::protobuf::compiler::python

    CodeGenerator implementation for generated Python Protobuf classes.

    If you create your own protocol compiler binary and you want it to support Python output, you can do so by registering an instance of this CodeGenerator with the CommandLineInterface in your main() function.

    Members

    Generator()
    virtual
    ~Generator()
    virtual bool
    Generate(const FileDescriptor * file, const std::string & parameter, GeneratorContext * generator_context, std::string * error) const
    CodeGenerator methods.
    virtual uint64_t
    GetSupportedFeatures() const
    Implement this to indicate what features this code generator supports. more...

    virtual uint64_t Generator::GetSupportedFeatures() const

    Implement this to indicate what features this code generator supports.

    This should be a bitwise OR of features from the Features enum in plugin.proto.

    diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.ruby_generator.md b/content/reference/cpp/api-docs/google.protobuf.compiler.ruby_generator.md index ed974126d..29e950174 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.ruby_generator.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.ruby_generator.md @@ -4,10 +4,10 @@ title = "ruby_generator.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ -

    #include <google/protobuf/compiler/ruby/ruby_generator.h>
    namespace google::protobuf::compiler::ruby

    Generates Ruby code for a given .proto file.

    Classes in this file

    CodeGenerator implementation for generated Ruby protocol buffer classes.

    class Generator: public CodeGenerator

    #include <google/protobuf/compiler/ruby/ruby_generator.h>
    namespace google::protobuf::compiler::ruby

    CodeGenerator implementation for generated Ruby protocol buffer classes.

    If you create your own protocol compiler binary and you want it to support Ruby output, you can do so by registering an instance of this CodeGenerator with the CommandLineInterface in your main() function.

    +

    #include <google/protobuf/compiler/ruby/ruby_generator.h>
    namespace google::protobuf::compiler::ruby

    Generates Ruby code for a given .proto file.

    Classes in this file

    CodeGenerator implementation for generated Ruby Protobuf classes.

    class Generator: public CodeGenerator

    #include <google/protobuf/compiler/ruby/ruby_generator.h>
    namespace google::protobuf::compiler::ruby

    CodeGenerator implementation for generated Ruby Protobuf classes.

    If you create your own protocol compiler binary and you want it to support Ruby output, you can do so by registering an instance of this CodeGenerator with the CommandLineInterface in your main() function.

    Members

    diff --git a/content/reference/cpp/api-docs/google.protobuf.descriptor.md b/content/reference/cpp/api-docs/google.protobuf.descriptor.md index 5a7924fcf..3680f7cfb 100644 --- a/content/reference/cpp/api-docs/google.protobuf.descriptor.md +++ b/content/reference/cpp/api-docs/google.protobuf.descriptor.md @@ -2,7 +2,7 @@ title = "descriptor.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ @@ -59,14 +59,14 @@ type = "docs"
  • Get the Descriptor or FileDescriptor for its containing scope, then call Descriptor::FindExtensionByName() or FileDescriptor::FindExtensionByName().
  • Given a DescriptorPool, call DescriptorPool::FindExtensionByNumber() or DescriptorPool::FindExtensionByPrintableName(). Use DescriptorPool to construct your own descriptors.
    • -

    Members

    enum
    Type
    Identifies a field type. more...
    enum
    CppType
    Specifies the C++ data type used to represent the field. more...
    enum
    Label
    Identifies whether the field is optional, required, or repeated. more...
    typedef
    FieldDescriptorProto Proto
    const int
    kMaxNumber = = (1 << 29) - 1
    Valid field numbers are positive integers up to kMaxNumber.
    const int
    kFirstReservedNumber = = 19000
    First field number reserved for the protocol buffer library implementation. more...
    const int
    kLastReservedNumber = = 19999
    Last field number reserved for the protocol buffer library implementation. more...
    int32
    default_value_int32_
    int64
    default_value_int64_
    uint32
    default_value_uint32_
    uint64
    default_value_uint64_
    float
    default_value_float_
    double
    default_value_double_
    bool
    default_value_bool_
    const EnumValueDescriptor *
    default_value_enum_
    const std::string *
    default_value_string_
    std::atomic< const Message * >
    default_generated_instance_
    const std::string &
    name() const
    Name of this field within the message.
    const std::string &
    full_name() const
    Fully-qualified name of the field.
    const std::string &
    json_name() const
    JSON name of this field.
    const FileDescriptor *
    file() const
    File in which this field was defined.
    bool
    is_extension() const
    Is this an extension field?
    int
    number() const
    Declared tag number.
    const std::string &
    lowercase_name() const
    Same as name() except converted to lower-case. more...
    const std::string &
    camelcase_name() const
    Same as name() except converted to camel-case. more...
    Type
    type() const
    Declared type of this field.
    const char *
    type_name() const
    Name of the declared type.
    CppType
    cpp_type() const
    C++ type of this field.
    const char *
    cpp_type_name() const
    Name of the C++ type.
    Label
    label() const
    optional/required/repeated
    bool
    is_required() const
    shorthand for label() == LABEL_REQUIRED
    bool
    is_optional() const
    shorthand for label() == LABEL_OPTIONAL
    bool
    is_repeated() const
    shorthand for label() == LABEL_REPEATED
    bool
    is_packable() const
    shorthand for is_repeated() && IsTypePackable(type())
    bool
    is_packed() const
    shorthand for is_packable() && options().packed()
    bool
    is_map() const
    shorthand for type() == TYPE_MESSAGE && message_type()->options().map_entry()
    bool
    has_optional_keyword() const
    Returns true if this field was syntactically written with "optional" in the .proto file. more...
    bool
    has_presence() const
    Returns true if this field tracks presence, ie. more...
    int
    index() const
    Index of this field within the message's field array, or the file or extension scope's extensions array.
    bool
    has_default_value() const
    Does this field have an explicitly-declared default value?
    bool
    has_json_name() const
    Whether the user has specified the json_name field option in the .proto file.
    int32
    default_value_int32() const
    Get the field default value if cpp_type() == CPPTYPE_INT32. more...
    int64
    default_value_int64() const
    Get the field default value if cpp_type() == CPPTYPE_INT64. more...
    uint32
    default_value_uint32() const
    Get the field default value if cpp_type() == CPPTYPE_UINT32. more...
    uint64
    default_value_uint64() const
    Get the field default value if cpp_type() == CPPTYPE_UINT64. more...
    float
    default_value_float() const
    Get the field default value if cpp_type() == CPPTYPE_FLOAT. more...
    double
    default_value_double() const
    Get the field default value if cpp_type() == CPPTYPE_DOUBLE. more...
    bool
    default_value_bool() const
    Get the field default value if cpp_type() == CPPTYPE_BOOL. more...
    const EnumValueDescriptor *
    default_value_enum() const
    Get the field default value if cpp_type() == CPPTYPE_ENUM. more...
    const std::string &
    default_value_string() const
    Get the field default value if cpp_type() == CPPTYPE_STRING. more...
    const Descriptor *
    containing_type() const
    The Descriptor for the message of which this is a field. more...
    const OneofDescriptor *
    containing_oneof() const
    If the field is a member of a oneof, this is the one, otherwise this is nullptr.
    const OneofDescriptor *
    real_containing_oneof() const
    If the field is a member of a non-synthetic oneof, returns the descriptor for the oneof, otherwise returns nullptr.
    int
    index_in_oneof() const
    If the field is a member of a oneof, returns the index in that oneof.
    const Descriptor *
    extension_scope() const
    An extension may be declared within the scope of another message. more...
    const Descriptor *
    message_type() const
    If type is TYPE_MESSAGE or TYPE_GROUP, returns a descriptor for the message or the group type. more...
    const EnumDescriptor *
    enum_type() const
    If type is TYPE_ENUM, returns a descriptor for the enum. more...
    const FieldOptions &
    options() const
    Get the FieldOptions for this field. more...
    void
    CopyTo(FieldDescriptorProto * proto) const
    std::string
    DebugString() const
    std::string
    DebugStringWithOptions(const DebugStringOptions & options) const
    const std::string &
    PrintableNameForExtension() const
    Returns full_name() except if the field is a MessageSet extension, in which case it returns the full_name() of the containing message type for backwards compatibility with proto1. more...
    static CppType
    TypeToCppType(Type type)
    Helper method to get the CppType for a particular Type.
    static const char *
    TypeName(Type type)
    Helper method to get the name of a Type.
    static const char *
    CppTypeName(CppType cpp_type)
    Helper method to get the name of a CppType.
    static bool
    IsTypePackable(Type field_type)
    Return true iff [[]packed = true] is valid for fields of this type.

    Source Location

    bool
    GetSourceLocation(SourceLocation * out_location) const
    Updates |*out_location| to the source location of the complete extent of this field declaration. more...

    enum FieldDescriptor::Type {
      TYPE_DOUBLE = = 1,
      TYPE_FLOAT = = 2,
      TYPE_INT64 = = 3,
      TYPE_UINT64 = = 4,
      TYPE_INT32 = = 5,
      TYPE_FIXED64 = = 6,
      TYPE_FIXED32 = = 7,
      TYPE_BOOL = = 8,
      TYPE_STRING = = 9,
      TYPE_GROUP = = 10,
      TYPE_MESSAGE = = 11,
      TYPE_BYTES = = 12,
      TYPE_UINT32 = = 13,
      TYPE_ENUM = = 14,
      TYPE_SFIXED32 = = 15,
      TYPE_SFIXED64 = = 16,
      TYPE_SINT32 = = 17,
      TYPE_SINT64 = = 18,
      MAX_TYPE = = 18
    }

    Identifies a field type.

    0 is reserved for errors. The order is weird for historical reasons. Types 12 and up are new in proto2.

    +

    Members

    enum
    Type
    Identifies a field type. more...
    enum
    CppType
    Specifies the C++ data type used to represent the field. more...
    enum
    Label
    Identifies whether the field is optional, required, or repeated. more...
    typedef
    FieldDescriptorProto Proto
    const int
    kMaxNumber = = (1 << 29) - 1
    Valid field numbers are positive integers up to kMaxNumber.
    const int
    kFirstReservedNumber = = 19000
    First field number reserved for the Protobuf library implementation. more...
    const int
    kLastReservedNumber = = 19999
    Last field number reserved for the Protobuf library implementation. more...
    int32
    default_value_int32_
    int64
    default_value_int64_
    uint32
    default_value_uint32_
    uint64
    default_value_uint64_
    float
    default_value_float_
    double
    default_value_double_
    bool
    default_value_bool_
    const EnumValueDescriptor *
    default_value_enum_
    const std::string *
    default_value_string_
    std::atomic< const Message * >
    default_generated_instance_
    const std::string &
    name() const
    Name of this field within the message.
    const std::string &
    full_name() const
    Fully-qualified name of the field.
    const std::string &
    json_name() const
    JSON name of this field.
    const FileDescriptor *
    file() const
    File in which this field was defined.
    bool
    is_extension() const
    Is this an extension field?
    int
    number() const
    Declared tag number.
    const std::string &
    lowercase_name() const
    Same as name() except converted to lower-case. more...
    const std::string &
    camelcase_name() const
    Same as name() except converted to camel-case. more...
    Type
    type() const
    Declared type of this field.
    const char *
    type_name() const
    Name of the declared type.
    CppType
    cpp_type() const
    C++ type of this field.
    const char *
    cpp_type_name() const
    Name of the C++ type.
    Label
    label() const
    optional/required/repeated
    bool
    is_required() const
    shorthand for label() == LABEL_REQUIRED
    bool
    is_optional() const
    shorthand for label() == LABEL_OPTIONAL
    bool
    is_repeated() const
    shorthand for label() == LABEL_REPEATED
    bool
    is_packable() const
    shorthand for is_repeated() && IsTypePackable(type())
    bool
    is_packed() const
    shorthand for is_packable() && options().packed()
    bool
    is_map() const
    shorthand for type() == TYPE_MESSAGE && message_type()->options().map_entry()
    bool
    has_optional_keyword() const
    Returns true if this field was syntactically written with "optional" in the .proto file. more...
    bool
    has_presence() const
    Returns true if this field tracks presence, ie. more...
    int
    index() const
    Index of this field within the message's field array, or the file or extension scope's extensions array.
    bool
    has_default_value() const
    Does this field have an explicitly-declared default value?
    bool
    has_json_name() const
    Whether the user has specified the json_name field option in the .proto file.
    int32
    default_value_int32() const
    Get the field default value if cpp_type() == CPPTYPE_INT32. more...
    int64
    default_value_int64() const
    Get the field default value if cpp_type() == CPPTYPE_INT64. more...
    uint32
    default_value_uint32() const
    Get the field default value if cpp_type() == CPPTYPE_UINT32. more...
    uint64
    default_value_uint64() const
    Get the field default value if cpp_type() == CPPTYPE_UINT64. more...
    float
    default_value_float() const
    Get the field default value if cpp_type() == CPPTYPE_FLOAT. more...
    double
    default_value_double() const
    Get the field default value if cpp_type() == CPPTYPE_DOUBLE. more...
    bool
    default_value_bool() const
    Get the field default value if cpp_type() == CPPTYPE_BOOL. more...
    const EnumValueDescriptor *
    default_value_enum() const
    Get the field default value if cpp_type() == CPPTYPE_ENUM. more...
    const std::string &
    default_value_string() const
    Get the field default value if cpp_type() == CPPTYPE_STRING. more...
    const Descriptor *
    containing_type() const
    The Descriptor for the message of which this is a field. more...
    const OneofDescriptor *
    containing_oneof() const
    If the field is a member of a oneof, this is the one, otherwise this is nullptr.
    const OneofDescriptor *
    real_containing_oneof() const
    If the field is a member of a non-synthetic oneof, returns the descriptor for the oneof, otherwise returns nullptr.
    int
    index_in_oneof() const
    If the field is a member of a oneof, returns the index in that oneof.
    const Descriptor *
    extension_scope() const
    An extension may be declared within the scope of another message. more...
    const Descriptor *
    message_type() const
    If type is TYPE_MESSAGE or TYPE_GROUP, returns a descriptor for the message or the group type. more...
    const EnumDescriptor *
    enum_type() const
    If type is TYPE_ENUM, returns a descriptor for the enum. more...
    const FieldOptions &
    options() const
    Get the FieldOptions for this field. more...
    void
    CopyTo(FieldDescriptorProto * proto) const
    std::string
    DebugString() const
    std::string
    DebugStringWithOptions(const DebugStringOptions & options) const
    const std::string &
    PrintableNameForExtension() const
    Returns full_name() except if the field is a MessageSet extension, in which case it returns the full_name() of the containing message type for backwards compatibility with proto1. more...
    static CppType
    TypeToCppType(Type type)
    Helper method to get the CppType for a particular Type.
    static const char *
    TypeName(Type type)
    Helper method to get the name of a Type.
    static const char *
    CppTypeName(CppType cpp_type)
    Helper method to get the name of a CppType.
    static bool
    IsTypePackable(Type field_type)
    Return true iff [[]packed = true] is valid for fields of this type.

    Source Location

    bool
    GetSourceLocation(SourceLocation * out_location) const
    Updates |*out_location| to the source location of the complete extent of this field declaration. more...

    enum FieldDescriptor::Type {
      TYPE_DOUBLE = = 1,
      TYPE_FLOAT = = 2,
      TYPE_INT64 = = 3,
      TYPE_UINT64 = = 4,
      TYPE_INT32 = = 5,
      TYPE_FIXED64 = = 6,
      TYPE_FIXED32 = = 7,
      TYPE_BOOL = = 8,
      TYPE_STRING = = 9,
      TYPE_GROUP = = 10,
      TYPE_MESSAGE = = 11,
      TYPE_BYTES = = 12,
      TYPE_UINT32 = = 13,
      TYPE_ENUM = = 14,
      TYPE_SFIXED32 = = 15,
      TYPE_SFIXED64 = = 16,
      TYPE_SINT32 = = 17,
      TYPE_SINT64 = = 18,
      MAX_TYPE = = 18
    }

    Identifies a field type.

    0 is reserved for errors. The order is weird for historical reasons. Types 12 and up are new in proto2.

    TYPE_DOUBLEdouble, exactly eight bytes on the wire.
    TYPE_FLOATfloat, exactly four bytes on the wire.
    TYPE_INT64

    int64, varint on the wire.

    Negative numbers take 10 bytes. Use TYPE_SINT64 if negative values are likely.

    TYPE_UINT64uint64, varint on the wire.
    TYPE_INT32

    int32, varint on the wire.

    Negative numbers take 10 bytes. Use TYPE_SINT32 if negative values are likely.

    TYPE_FIXED64uint64, exactly eight bytes on the wire.
    TYPE_FIXED32uint32, exactly four bytes on the wire.
    TYPE_BOOLbool, varint on the wire.
    TYPE_STRINGUTF-8 text.
    TYPE_GROUPTag-delimited message. Deprecated.
    TYPE_MESSAGELength-delimited message.
    TYPE_BYTESArbitrary byte array.
    TYPE_UINT32uint32, varint on the wire
    TYPE_ENUMEnum, varint on the wire.
    TYPE_SFIXED32int32, exactly four bytes on the wire
    TYPE_SFIXED64int64, exactly eight bytes on the wire
    TYPE_SINT32int32, ZigZag-encoded varint on the wire
    TYPE_SINT64int64, ZigZag-encoded varint on the wire
    MAX_TYPEConstant useful for defining lookup tables indexed by Type.

    enum FieldDescriptor::CppType {
      CPPTYPE_INT32 = = 1,
      CPPTYPE_INT64 = = 2,
      CPPTYPE_UINT32 = = 3,
      CPPTYPE_UINT64 = = 4,
      CPPTYPE_DOUBLE = = 5,
      CPPTYPE_FLOAT = = 6,
      CPPTYPE_BOOL = = 7,
      CPPTYPE_ENUM = = 8,
      CPPTYPE_STRING = = 9,
      CPPTYPE_MESSAGE = = 10,
      MAX_CPPTYPE = = 10
    }

    Specifies the C++ data type used to represent the field.

    There is a fixed mapping from Type to CppType where each Type maps to exactly one CppType. 0 is reserved for errors.

    CPPTYPE_INT32TYPE_INT32, TYPE_SINT32, TYPE_SFIXED32.
    CPPTYPE_INT64TYPE_INT64, TYPE_SINT64, TYPE_SFIXED64.
    CPPTYPE_UINT32TYPE_UINT32, TYPE_FIXED32.
    CPPTYPE_UINT64TYPE_UINT64, TYPE_FIXED64.
    CPPTYPE_DOUBLETYPE_DOUBLE.
    CPPTYPE_FLOATTYPE_FLOAT.
    CPPTYPE_BOOLTYPE_BOOL.
    CPPTYPE_ENUMTYPE_ENUM.
    CPPTYPE_STRINGTYPE_STRING, TYPE_BYTES.
    CPPTYPE_MESSAGETYPE_MESSAGE, TYPE_GROUP.
    MAX_CPPTYPEConstant useful for defining lookup tables indexed by CppType.

    enum FieldDescriptor::Label {
      LABEL_OPTIONAL = = 1,
      LABEL_REQUIRED = = 2,
      LABEL_REPEATED = = 3,
      MAX_LABEL = = 3
    }

    Identifies whether the field is optional, required, or repeated.

    0 is reserved for errors.

    -
    LABEL_OPTIONALoptional
    LABEL_REQUIREDrequired
    LABEL_REPEATEDrepeated
    MAX_LABELConstant useful for defining lookup tables indexed by Label.

    const int FieldDescriptor::kFirstReservedNumber = = 19000

    First field number reserved for the protocol buffer library implementation.

    Users may not declare fields that use reserved numbers.

    -

    const int FieldDescriptor::kLastReservedNumber = = 19999

    Last field number reserved for the protocol buffer library implementation.

    Users may not declare fields that use reserved numbers.

    -

    const std::string &
        FieldDescriptor::lowercase_name() const

    Same as name() except converted to lower-case.

    This (and especially the FindFieldByLowercaseName() method) can be useful when parsing formats which prefer to use lowercase naming style. (Although, technically field names should be lowercased anyway according to the protobuf style guide, so this only makes a difference when dealing with old .proto files which do not follow the guide.)

    +
    LABEL_OPTIONALoptional
    LABEL_REQUIREDrequired
    LABEL_REPEATEDrepeated
    MAX_LABELConstant useful for defining lookup tables indexed by Label.

    const int FieldDescriptor::kFirstReservedNumber = = 19000

    First field number reserved for the Protobuf library implementation.

    Users may not declare fields that use reserved numbers.

    +

    const int FieldDescriptor::kLastReservedNumber = = 19999

    Last field number reserved for the Protobuf library implementation.

    Users may not declare fields that use reserved numbers.

    +

    const std::string &
        FieldDescriptor::lowercase_name() const

    Same as name() except converted to lower-case.

    This (and especially the FindFieldByLowercaseName() method) can be useful when parsing formats which prefer to use lowercase naming style. (Although, technically field names should be lowercased anyway according to the Protobuf style guide, so this only makes a difference when dealing with old .proto files which do not follow the guide.)

    const std::string &
        FieldDescriptor::camelcase_name() const

    Same as name() except converted to camel-case.

    In this conversion, any time an underscore appears in the name, it is removed and the next letter is capitalized. Furthermore, the first letter of the name is lower-cased. Examples: 

    FooBar -> fooBar
 foo_bar -> fooBar
diff --git a/content/reference/cpp/api-docs/google.protobuf.descriptor.pb.md b/content/reference/cpp/api-docs/google.protobuf.descriptor.pb.md
index b0dfacd6c..3e966f8a3 100644
--- a/content/reference/cpp/api-docs/google.protobuf.descriptor.pb.md
+++ b/content/reference/cpp/api-docs/google.protobuf.descriptor.pb.md
@@ -2,11 +2,11 @@
 title = "descriptor.pb.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
-
    #include <google/protobuf/descriptor.pb.h>
    namespace google::protobuf
    Protocol buffer representations of descriptors.
    This file defines a set of protocol message classes which represent the same information represented by the classes defined in descriptor.h.  You can convert a FileDescriptorProto to a FileDescriptor using the DescriptorPool class.  Thus, the classes in this file allow protocol type definitions to be communicated efficiently between processes.
    
+
    #include <google/protobuf/descriptor.pb.h>
    namespace google::protobuf
    Protobuf representations of descriptors.
    This file defines a set of protocol message classes which represent the same information represented by the classes defined in descriptor.h.  You can convert a FileDescriptorProto to a FileDescriptor using the DescriptorPool class.  Thus, the classes in this file allow protocol type definitions to be communicated efficiently between processes.
    
 
 
    The protocol compiler currently doesn't support auto-generated documentation, hence this page contains no descriptions.  This file was generated by the protocol compiler from descriptor.proto, whose contents are as follows:
    
 
diff --git a/content/reference/cpp/api-docs/google.protobuf.descriptor_database.md b/content/reference/cpp/api-docs/google.protobuf.descriptor_database.md
index c2f28e434..c787ecac9 100644
--- a/content/reference/cpp/api-docs/google.protobuf.descriptor_database.md
+++ b/content/reference/cpp/api-docs/google.protobuf.descriptor_database.md
@@ -2,7 +2,7 @@
 title = "descriptor_database.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
diff --git a/content/reference/cpp/api-docs/google.protobuf.dynamic_message.md b/content/reference/cpp/api-docs/google.protobuf.dynamic_message.md
index 17d432754..be22de338 100644
--- a/content/reference/cpp/api-docs/google.protobuf.dynamic_message.md
+++ b/content/reference/cpp/api-docs/google.protobuf.dynamic_message.md
@@ -4,7 +4,7 @@
 title = "dynamic_message.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
diff --git a/content/reference/cpp/api-docs/google.protobuf.io.coded_stream.md b/content/reference/cpp/api-docs/google.protobuf.io.coded_stream.md
index 04db2bc81..c1bfca934 100644
--- a/content/reference/cpp/api-docs/google.protobuf.io.coded_stream.md
+++ b/content/reference/cpp/api-docs/google.protobuf.io.coded_stream.md
@@ -2,13 +2,13 @@
 title = "coded_stream.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
 
    #include <google/protobuf/io/coded_stream.h>
    namespace google::protobuf::io
    This file contains the CodedInputStream and CodedOutputStream classes, which wrap a ZeroCopyInputStream or ZeroCopyOutputStream, respectively, and allow you to read or write individual pieces of data in various formats. 
    In particular, these implement the varint encoding for integers, a simple variable-length encoding in which smaller numbers take fewer bytes.
    
 
-
    Typically these classes will only be used internally by the protocol buffer library in order to encode and decode protocol buffers. Clients of the library only need to know about this class if they wish to write custom message parsing or serialization procedures.
    
+
    Typically these classes will only be used internally by the Protobuf library in order to encode and decode Protobuf messages. Clients of the library only need to know about this class if they wish to write custom message parsing or serialization procedures.
    
 
 
    CodedOutputStream example: 
    
 
@@ -173,7 +173,7 @@ delete coded_output;

    void CodedOutputStream::EnableAliasing(
            bool enabled)

    Instructs the CodedOutputStream to allow the underlying ZeroCopyOutputStream to hold pointers to the original structure instead of copying, if it supports it (i.e.

    output->AllowsAliasing() is true). If the underlying stream does not support aliasing, then enabling it has no affect. For now, this only affects the behavior of WriteRawMaybeAliased().

    NOTE: It is caller's responsibility to ensure that the chunk of memory remains live until all of the data has been consumed from the stream.

    void CodedOutputStream::SetSerializationDeterministic(
            bool value)

    Indicate to the serializer whether the user wants derministic serialization.

    The default when this is not called comes from the global default, controlled by SetDefaultSerializationDeterministic.

    -

    What deterministic serialization means is entirely up to the driver of the serialization process (i.e. the caller of methods like WriteVarint32). In the case of serializing a proto buffer message using one of the methods of MessageLite, this means that for a given binary equal messages will always be serialized to the same bytes. This implies:

    +

    What deterministic serialization means is entirely up to the driver of the serialization process (i.e. the caller of methods like WriteVarint32). In the case of serializing a Protobuf message using one of the methods of MessageLite, this means that for a given binary equal messages will always be serialized to the same bytes. This implies:

    Repeated serialization of a message will return the same bytes.
 
 Different processes running the same binary (including on different
diff --git a/content/reference/cpp/api-docs/google.protobuf.io.gzip_stream.md b/content/reference/cpp/api-docs/google.protobuf.io.gzip_stream.md
index dabc10c3b..1c87a23c0 100644
--- a/content/reference/cpp/api-docs/google.protobuf.io.gzip_stream.md
+++ b/content/reference/cpp/api-docs/google.protobuf.io.gzip_stream.md
@@ -2,7 +2,7 @@
 title = "gzip_stream.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
diff --git a/content/reference/cpp/api-docs/google.protobuf.io.printer.md b/content/reference/cpp/api-docs/google.protobuf.io.printer.md
index f1048c50d..1623248a2 100644
--- a/content/reference/cpp/api-docs/google.protobuf.io.printer.md
+++ b/content/reference/cpp/api-docs/google.protobuf.io.printer.md
@@ -2,13 +2,13 @@
 title = "printer.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
-
    #include <google/protobuf/io/printer.h>
    namespace google::protobuf::io
    Utility class for writing text to a ZeroCopyOutputStream. 
    Classes in this file
    Records annotations about a Printer's output. 
    Records annotations about a Printer's output to the given protocol buffer, assuming that the buffer has an ::Annotation message exposing path, source_file, begin and end fields. 
    class AnnotationCollector
    #include <google/protobuf/io/printer.h>
    namespace google::protobuf::io
    Records annotations about a Printer's output. 
    Known subclasses:
    Members
    typedef
    std::pair< std::pair< size_t, size_t >, std::string > Annotation
    Annotation is a offset range and a payload pair. 
    virtual void
    AddAnnotation(size_t begin_offset, size_t end_offset, const std::string & file_path, const std::vector< int > & path)  = 0
    Records that the bytes in file_path beginning with begin_offset and ending before end_offset are associated with the SourceCodeInfo-style path. 
    virtual void
    AddAnnotationNew(Annotation & )
    virtual 
    ~AnnotationCollector()
     
    virtual void AnnotationCollector::AddAnnotationNew(
            Annotation & )
    Just a vector of range, payload pairs stored in a context should suffice. 
    
+
    #include <google/protobuf/io/printer.h>
    namespace google::protobuf::io
    Utility class for writing text to a ZeroCopyOutputStream. 
    Classes in this file
    Records annotations about a Printer's output. 
    Records annotations about a Printer's output to the given Protobuf message, assuming that the message has an ::Annotation message exposing path, source_file, begin and end fields. 
    class AnnotationCollector
    #include <google/protobuf/io/printer.h>
    namespace google::protobuf::io
    Records annotations about a Printer's output. 
    Known subclasses:
    Members
    typedef
    std::pair< std::pair< size_t, size_t >, std::string > Annotation
    Annotation is a offset range and a payload pair. 
    virtual void
    AddAnnotation(size_t begin_offset, size_t end_offset, const std::string & file_path, const std::vector< int > & path)  = 0
    Records that the bytes in file_path beginning with begin_offset and ending before end_offset are associated with the SourceCodeInfo-style path. 
    virtual void
    AddAnnotationNew(Annotation & )
    virtual 
    ~AnnotationCollector()
     
    virtual void AnnotationCollector::AddAnnotationNew(
            Annotation & )
    Just a vector of range, payload pairs stored in a context should suffice. 
    
 
-
    template class AnnotationProtoCollector: public AnnotationCollector
    #include <google/protobuf/io/printer.h>
    namespace google::protobuf::io

    template <typename >
    Records annotations about a Printer's output to the given protocol buffer, assuming that the buffer has an ::Annotation message exposing path, source_file, begin and end fields. 
    Members
    explicit 
    AnnotationProtoCollector(AnnotationProto * annotation_proto)
    annotation_proto is the protocol buffer to which new Annotations should be added.  more...
    virtual void
    AddAnnotation(size_t begin_offset, size_t end_offset, const std::string & file_path, const std::vector< int > & path)
    virtual void
    AddAnnotationNew(Annotation & a)
     
    explicit  AnnotationProtoCollector::AnnotationProtoCollector(
            AnnotationProto * annotation_proto)
    annotation_proto is the protocol buffer to which new Annotations should be added. 
    It is not owned by the AnnotationProtoCollector. 
    
+
    template class AnnotationProtoCollector: public AnnotationCollector
    #include <google/protobuf/io/printer.h>
    namespace google::protobuf::io

    template <typename >
    Records annotations about a Printer's output to the given Protobuf message, assuming that the message has an ::Annotation message exposing path, source_file, begin and end fields. 
    Members
    explicit 
    AnnotationProtoCollector(AnnotationProto * annotation_proto)
    annotation_proto is the Protobuf message to which new Annotations should be added.  more...
    virtual void
    AddAnnotation(size_t begin_offset, size_t end_offset, const std::string & file_path, const std::vector< int > & path)
    virtual void
    AddAnnotationNew(Annotation & a)
     
    explicit  AnnotationProtoCollector::AnnotationProtoCollector(
            AnnotationProto * annotation_proto)
    annotation_proto is the Protobuf message to which new Annotations should be added. 
    It is not owned by the AnnotationProtoCollector. 
    
 
    class Printer
    #include <google/protobuf/io/printer.h>
    namespace google::protobuf::io
    Members
    Printer(ZeroCopyOutputStream * output, char variable_delimiter)
    Create a printer that writes text to the given output stream.  more...
    Printer(ZeroCopyOutputStream * output, char variable_delimiter, AnnotationCollector * annotation_collector)
    Create a printer that writes text to the given output stream.  more...
    ~Printer()
    template void
    Annotate(const char * varname, const SomeDescriptor * descriptor)
    Link a substitution variable emitted by the last call to Print to the object described by descriptor. 
    template void
    Annotate(const char * begin_varname, const char * end_varname, const SomeDescriptor * descriptor)
    Link the output range defined by the substitution variables as emitted by the last call to Print to the object described by descriptor.  more...
    void
    Annotate(const char * varname, const std::string & file_name)
    Link a substitution variable emitted by the last call to Print to the file with path file_name. 
    void
    Annotate(const char * begin_varname, const char * end_varname, const std::string & file_name)
    Link the output range defined by the substitution variables as emitted by the last call to Print to the file with path file_name.  more...
    void
    Print(const std::map< std::string, std::string > & variables, const char * text)
    Print some text after applying variable substitutions.  more...
    template void
    Print(const char * text, const Args &... args)
    Like the first Print(), except the substitutions are given as parameters. 
    void
    Indent()
    Indent text by two spaces.  more...
    void
    Outdent()
    Reduces the current indent level by two spaces, or crashes if the indent level is zero. 
    void
    PrintRaw(const std::string & data)
    Write a string to the output buffer.  more...
    void
    PrintRaw(const char * data)
    Write a zero-delimited string to output buffer.  more...
    void
    WriteRaw(const char * data, int size)
    Write some bytes to the output buffer.  more...
    void
    FormatInternal(const std::vector< std::string > & args, const std::map< std::string, std::string > & vars, const char * format)
    FormatInternal is a helper function not meant to use directly, use compiler::cpp::Formatter instead.  more...
    bool
    failed() const
    True if any write to the underlying stream failed.  more...
     
     Printer::Printer(
            ZeroCopyOutputStream * output,
            char variable_delimiter)
    Create a printer that writes text to the given output stream. 
    Use the given character as the delimiter for variables. 
    
 
     
     Printer::Printer(
            ZeroCopyOutputStream * output,
            char variable_delimiter,
            AnnotationCollector * annotation_collector)
    Create a printer that writes text to the given output stream. 
    Use the given character as the delimiter for variables. If annotation_collector is not null, Printer will provide it with annotations about code written to the stream. annotation_collector is not owned by Printer. 
    
 
     
    template void Printer::Annotate(
            const char * begin_varname,
            const char * end_varname,
            const SomeDescriptor * descriptor)
    Link the output range defined by the substitution variables as emitted by the last call to Print to the object described by descriptor. 
    The range begins at begin_varname's value and ends after the last character of the value substituted for end_varname. 
    
diff --git a/content/reference/cpp/api-docs/google.protobuf.io.tokenizer.md b/content/reference/cpp/api-docs/google.protobuf.io.tokenizer.md
index 0b05302c3..3845f9d76 100644
--- a/content/reference/cpp/api-docs/google.protobuf.io.tokenizer.md
+++ b/content/reference/cpp/api-docs/google.protobuf.io.tokenizer.md
@@ -2,7 +2,7 @@
 title = "tokenizer.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
diff --git a/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream.md b/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream.md
index 9ccbcda3c..0151e5ab3 100644
--- a/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream.md
+++ b/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream.md
@@ -2,11 +2,11 @@
 title = "zero_copy_stream.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
-
    #include <google/protobuf/io/zero_copy_stream.h>
    namespace google::protobuf::io
    This file contains the ZeroCopyInputStream and ZeroCopyOutputStream interfaces, which represent abstract I/O streams to and from which protocol buffers can be read and written. 
    For a few simple implementations of these interfaces, see zero_copy_stream_impl.h.
    
+
    #include <google/protobuf/io/zero_copy_stream.h>
    namespace google::protobuf::io
    This file contains the ZeroCopyInputStream and ZeroCopyOutputStream interfaces, which represent abstract I/O streams to and from which Protobuf messages can be read and written. 
    For a few simple implementations of these interfaces, see zero_copy_stream_impl.h.
    
 
 
    These interfaces are different from classic I/O streams in that they try to minimize the amount of data copying that needs to be done. To accomplish this, responsibility for allocating buffers is moved to the stream object, rather than being the responsibility of the caller. So, the stream can return a buffer which actually points directly into the final data structure where the bytes are to be stored, and the caller can interact directly with that buffer, eliminating an intermediate copy operation.
    
 
diff --git a/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream_impl.md b/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream_impl.md
index e9a433053..f14a8f579 100644
--- a/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream_impl.md
+++ b/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream_impl.md
@@ -2,11 +2,11 @@
 title = "zero_copy_stream_impl.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
-
    #include <google/protobuf/io/zero_copy_stream_impl.h>
    namespace google::protobuf::io
    This file contains common implementations of the interfaces defined in zero_copy_stream.h which are only included in the full (non-lite) protobuf library. 
    These implementations include Unix file descriptors and C++ iostreams. See also: zero_copy_stream_impl_lite.h 
    
+
    #include <google/protobuf/io/zero_copy_stream_impl.h>
    namespace google::protobuf::io
    This file contains common implementations of the interfaces defined in zero_copy_stream.h which are only included in the full (non-lite) Protobuf library. 
    These implementations include Unix file descriptors and C++ iostreams. See also: zero_copy_stream_impl_lite.h 
    
 
 
    Classes in this file
    A ZeroCopyInputStream which reads from a file descriptor. 
    A ZeroCopyOutputStream which writes to a file descriptor. 
    A ZeroCopyInputStream which reads from a C++ istream. 
    A ZeroCopyOutputStream which writes to a C++ ostream. 
    A ZeroCopyInputStream which reads from several other streams in sequence. 
    class FileInputStream: public ZeroCopyInputStream
    #include <google/protobuf/io/zero_copy_stream_impl.h>
    namespace google::protobuf::io
    A ZeroCopyInputStream which reads from a file descriptor. 
    FileInputStream is preferred over using an ifstream with IstreamInputStream. The latter will introduce an extra layer of buffering, harming performance. Also, it's conceivable that FileInputStream could someday be enhanced to use zero-copy file descriptors on OSs which support them. 
    
 
    Members
    explicit 
    FileInputStream(int file_descriptor, int block_size = -1)
    Creates a stream that reads from the given Unix file descriptor.  more...
    bool
    Close()
    Flushes any buffers and closes the underlying file.  more...
    void
    SetCloseOnDelete(bool value)
    By default, the file descriptor is not closed when the stream is destroyed.  more...
    int
    GetErrno() const
    If an I/O error has occurred on this file descriptor, this is the errno from that error.  more...
    implements ZeroCopyInputStream
    virtual bool
    Next(const void ** data, int * size)
    Obtains a chunk of data from the stream.  more...
    virtual void
    BackUp(int count)
    Backs up a number of bytes, so that the next call to Next() returns data again that was already returned by the last call to Next().  more...
    virtual bool
    Skip(int count)
    Skips a number of bytes.  more...
    virtual int64_t
    ByteCount() const
    Returns the total number of bytes read since this object was created. 
     
    explicit  FileInputStream::FileInputStream(
            int file_descriptor,
            int block_size = -1)
    Creates a stream that reads from the given Unix file descriptor. 
    If a block_size is given, it specifies the number of bytes that should be read and returned with each call to Next(). Otherwise, a reasonable default is used. 
    
diff --git a/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream_impl_lite.md b/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream_impl_lite.md
index a04133874..9a773842e 100644
--- a/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream_impl_lite.md
+++ b/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream_impl_lite.md
@@ -2,11 +2,11 @@
 title = "zero_copy_stream_iml_lite.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
-
    #include <google/protobuf/io/zero_copy_stream_impl_lite.h>
    namespace google::protobuf::io
    This file contains common implementations of the interfaces defined in zero_copy_stream.h which are included in the "lite" protobuf library. 
    These implementations cover I/O on raw arrays and strings, as well as adaptors which make it easy to implement streams based on traditional streams. Of course, many users will probably want to write their own implementations of these interfaces specific to the particular I/O abstractions they prefer to use, but these should cover the most common cases. 
    
+
    #include <google/protobuf/io/zero_copy_stream_impl_lite.h>
    namespace google::protobuf::io
    This file contains common implementations of the interfaces defined in zero_copy_stream.h which are included in the "lite" Protobuf library. 
    These implementations cover I/O on raw arrays and strings, as well as adaptors which make it easy to implement streams based on traditional streams. Of course, many users will probably want to write their own implementations of these interfaces specific to the particular I/O abstractions they prefer to use, but these should cover the most common cases. 
    
 
 
    Classes in this file
    A ZeroCopyInputStream backed by an in-memory array of bytes. 
    A ZeroCopyOutputStream backed by an in-memory array of bytes. 
    A ZeroCopyOutputStream which appends bytes to a string. 
    A generic traditional input stream interface. 
    A generic traditional output stream interface. 
    A ZeroCopyInputStream which wraps some other stream and limits it to a particular byte count. 
    File Members
    These definitions are not part of any class.
    char *
    mutable_string_data(std::string * s)
    Return a pointer to mutable characters underlying the given string.  more...
    std::pair< char *, bool >
    as_string_data(std::string * s)
    as_string_data(s) is equivalent to ({ char* p = mutable_string_data(s); make_pair(p, p != NULL); }) Sometimes it's faster: in some scenarios p cannot be NULL, and then the code can avoid that check. 
     
    char * io::mutable_string_data(
            std::string * s)
    Return a pointer to mutable characters underlying the given string. 
    The return value is valid until the next time the string is resized. We trust the caller to treat the return value as an array of length s->size(). 
    
 
    class ArrayInputStream: public ZeroCopyInputStream
    #include <google/protobuf/io/zero_copy_stream_impl_lite.h>
    namespace google::protobuf::io
    A ZeroCopyInputStream backed by an in-memory array of bytes. 
    Members
    ArrayInputStream(const void * data, int size, int block_size = -1)
    Create an InputStream that returns the bytes pointed to by "data".  more...
    ~ArrayInputStream()
    implements ZeroCopyInputStream
    virtual bool
    Next(const void ** data, int * size)
    Obtains a chunk of data from the stream.  more...
    virtual void
    BackUp(int count)
    Backs up a number of bytes, so that the next call to Next() returns data again that was already returned by the last call to Next().  more...
    virtual bool
    Skip(int count)
    Skips a number of bytes.  more...
    virtual int64_t
    ByteCount() const
    Returns the total number of bytes read since this object was created. 
     
     ArrayInputStream::ArrayInputStream(
            const void * data,
            int size,
            int block_size = -1)
    Create an InputStream that returns the bytes pointed to by "data". 
    "data" remains the property of the caller but must remain valid until the stream is destroyed. If a block_size is given, calls to Next() will return data blocks no larger than the given size. Otherwise, the first call to Next() returns the entire array. block_size is mainly useful for testing; in production you would probably never want to set it. 
    
diff --git a/content/reference/cpp/api-docs/google.protobuf.map.md b/content/reference/cpp/api-docs/google.protobuf.map.md
index f0022eb39..bc0dc12d8 100644
--- a/content/reference/cpp/api-docs/google.protobuf.map.md
+++ b/content/reference/cpp/api-docs/google.protobuf.map.md
@@ -4,14 +4,14 @@
 title = "map.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
-
    #include <google/protobuf/map.h>
    namespace google::protobuf
    This file defines the map container and its helpers to support protobuf maps. 
    The Map and MapIterator types are provided by this header file. Please avoid using other types defined here, unless they are public types within Map or MapIterator, such as Map::value_type. 
    
+
    #include <google/protobuf/map.h>
    namespace google::protobuf
    This file defines the map container and its helpers to support Protobuf maps. 
    The Map and MapIterator types are provided by this header file. Please avoid using other types defined here, unless they are public types within Map or MapIterator, such as Map::value_type. 
    
 
-
    Classes in this file
    This is the class for Map's internal value_type. 
    Map is an associative container type used to store protobuf map fields. 
    Iterators. 
    template alias MapPair
    #include <google/protobuf/map.h>
    namespace google::protobuf

    template <typename , typename >
    This is the class for Map's internal value_type, which is just an alias to std::pair. 
    
-
    template class Map
    #include <google/protobuf/map.h>
    namespace google::protobuf

    template <typename , typename >
    Map is an associative container type used to store protobuf map fields. 
    Each Map instance may or may not use a different hash function, a different iteration order, and so on. E.g., please don't examine implementation details to decide if the following would work: Map<int, int> m0, m1; m0[0] = m1[0] = m0[1] = m1[1] = 0; assert(m0.begin()->first == m1.begin()->first); // Bug!
    
+
    Classes in this file
    This is the class for Map's internal value_type. 
    Map is an associative container type used to store Protobuf map fields. 
    Iterators. 
    template alias MapPair
    #include <google/protobuf/map.h>
    namespace google::protobuf

    template <typename , typename >
    This is the class for Map's internal value_type, which is just an alias to std::pair. 
    
+
    template class Map
    #include <google/protobuf/map.h>
    namespace google::protobuf

    template <typename , typename >
    Map is an associative container type used to store Protobuf map fields. 
    Each Map instance may or may not use a different hash function, a different iteration order, and so on. E.g., please don't examine implementation details to decide if the following would work: Map<int, int> m0, m1; m0[0] = m1[0] = m0[1] = m1[1] = 0; assert(m0.begin()->first == m1.begin()->first); // Bug!
    
 
    Map's interface is similar to std::unordered_map, except that Map is not designed to play well with exceptions. 
    
 
    Members
    typedef
    Key key_type
    typedef
    T mapped_type
    typedef
    MapPair< Key, T > value_type
    typedef
    value_type * pointer
    typedef
    const value_type * const_pointer
    typedef
    value_type & reference
    typedef
    const value_type & const_reference
    typedef
    size_t size_type
    typedef
    typename internal::TransparentSupport< Key >::hash hasher
    constexpr
    Map()
    explicit 
    Map(Arena * arena)
    Map(const Map & other)
    Map(Map && other)
    Map &
    operator=(Map && other)
    template 
    Map(const InputIt & first, const InputIt & last)
    ~Map()
    iterator
    begin()
    iterator
    end()
    const_iterator
    begin() const
    const_iterator
    end() const
    const_iterator
    cbegin() const
    const_iterator
    cend() const
    size_type
    size() const
    Capacity. 
    bool
    empty() const
    template T &
    operator[](const key_arg< K > & key)
    Element access. 
    template T &
    operator[](key_arg< K > && key)
    template const T &
    at(const key_arg< K > & key) const
    template T &
    at(const key_arg< K > & key)
    template size_type
    count(const key_arg< K > & key) const
    Lookup. 
    template const_iterator
    find(const key_arg< K > & key) const
    template iterator
    find(const key_arg< K > & key)
    template bool
    contains(const key_arg< K > & key) const
    template std::pair< const_iterator, const_iterator >
    equal_range(const key_arg< K > & key) const
    template std::pair< iterator, iterator >
    equal_range(const key_arg< K > & key)
    std::pair< iterator, bool >
    insert(const value_type & value)
    insert 
    template void
    insert(InputIt first, InputIt last)
    void
    insert(std::initializer_list< value_type > values)
    template size_type
    erase(const key_arg< K > & key)
    Erase and clear. 
    iterator
    erase(iterator pos)
    void
    erase(iterator first, iterator last)
    void
    clear()
    Map &
    operator=(const Map & other)
    Assign. 
    void
    swap(Map & other)
    void
    InternalSwap(Map & other)
    hasher
    hash_function() const
    Access to hasher.  more...
    size_t
    SpaceUsedExcludingSelfLong() const
     
    hasher Map::hash_function() const
    Access to hasher. 
    Currently this returns a copy, but it may be modified to return a const reference in the future. 
    
 
    class Map::const_iterator
    #include <google/protobuf/map.h>
    namespace google::protobuf
    Iterators. 
    Members
    typedef
    std::forward_iterator_tag iterator_category
    typedef
    typename Map::value_type value_type
    typedef
    ptrdiff_t difference_type
    typedef
    const value_type * pointer
    typedef
    const value_type & reference
    const_iterator()
    explicit 
    const_iterator(const InnerIt & it)
    const_reference
    operator*() const
    const_pointer
    operator->() const
    const_iterator &
    operator++()
    const_iterator
    operator++(int )
    class Map::iterator
    #include <google/protobuf/map.h>
    namespace google::protobuf
    Members
    typedef
    std::forward_iterator_tag iterator_category
    typedef
    typename Map::value_type value_type
    typedef
    ptrdiff_t difference_type
    typedef
    value_type * pointer
    typedef
    value_type & reference
    iterator()
    explicit 
    iterator(const InnerIt & it)
    reference
    operator*() const
    pointer
    operator->() const
    iterator &
    operator++()
    iterator
    operator++(int )
    operator const_iterator() const
    Allow implicit conversion to const_iterator. 
    
diff --git a/content/reference/cpp/api-docs/google.protobuf.message.md b/content/reference/cpp/api-docs/google.protobuf.message.md
index 2ff71173f..d6b930db9 100644
--- a/content/reference/cpp/api-docs/google.protobuf.message.md
+++ b/content/reference/cpp/api-docs/google.protobuf.message.md
@@ -2,7 +2,7 @@
 title = "message.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
@@ -154,9 +154,9 @@ CPPTYPE_MESSAGE      generated message type or google::protobuf::Message

    A RepeatedFieldRef object can be copied and the resulted object will point to the same repeated field in the same message. The object can be used as long as the message is not destroyed.

    Note that to use this method users need to include the header file "reflection.h" (which defines the RepeatedFieldRef class templates).

    template const RepeatedField< T > &
        Reflection::GetRepeatedField(
            const Message & msg,
            const FieldDescriptor * d) const

    DEPRECATED.

    Please use GetRepeatedFieldRef().

    -

    for T = Cord and all protobuf scalar types except enums.

    +

    for T = Cord and all Protobuf scalar types except enums.

    template RepeatedField< T > *
        Reflection::MutableRepeatedField(
            Message * msg,
            const FieldDescriptor * d) const

    DEPRECATED.

    Please use GetMutableRepeatedFieldRef().

    -

    for T = Cord and all protobuf scalar types except enums.

    +

    for T = Cord and all Protobuf scalar types except enums.

    template const RepeatedPtrField< T > &
        Reflection::GetRepeatedPtrField(
            const Message & msg,
            const FieldDescriptor * d) const

    DEPRECATED.

    Please use GetRepeatedFieldRef().

    for T = std::string, google::protobuf::internal::StringPieceField 

    google::protobuf::Message & descendants.
    diff --git a/content/reference/cpp/api-docs/google.protobuf.message_lite.md b/content/reference/cpp/api-docs/google.protobuf.message_lite.md index d6fa41333..ee01ba1f8 100644 --- a/content/reference/cpp/api-docs/google.protobuf.message_lite.md +++ b/content/reference/cpp/api-docs/google.protobuf.message_lite.md @@ -4,38 +4,38 @@ title = "message_lite.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ -

    #include <google/protobuf/message_lite.h>
    namespace google::protobuf

    Defines MessageLite, the abstract interface implemented by all (lite and non-lite) protocol message objects.

    Classes in this file

    Interface to light weight protocol messages.

    File Members

    These definitions are not part of any class.
    void
    ShutdownProtobufLibrary()
    Shut down the entire protocol buffers library, deleting all static-duration objects allocated by the library or by generated .pb.cc files. more...

    void protobuf::ShutdownProtobufLibrary()

    Shut down the entire protocol buffers library, deleting all static-duration objects allocated by the library or by generated .pb.cc files.

    There are two reasons you might want to call this:

    +

    #include <google/protobuf/message_lite.h>
    namespace google::protobuf

    Defines MessageLite, the abstract interface implemented by all (lite and non-lite) protocol message objects.

    Classes in this file

    Interface to light weight protocol messages.

    File Members

    These definitions are not part of any class.
    void
    ShutdownProtobufLibrary()
    Shut down the entire Protobuf library, deleting all static-duration objects allocated by the library or by generated .pb.cc files. more...

    void protobuf::ShutdownProtobufLibrary()

    Shut down the entire Protobuf library, deleting all static-duration objects allocated by the library or by generated .pb.cc files.

    There are two reasons you might want to call this:

    • You use a draconian definition of "memory leak" in which you expect every single malloc() to have a corresponding free(), even for objects which live until program exit.
    • You are writing a dynamically-loaded library which needs to clean up after itself when the library is unloaded.
    -

    It is safe to call this multiple times. However, it is not safe to use any other part of the protocol buffers library after ShutdownProtobufLibrary() has been called. Furthermore this call is not thread safe, user needs to synchronize multiple calls.

    +

    It is safe to call this multiple times. However, it is not safe to use any other part of the Protobuf library after ShutdownProtobufLibrary() has been called. Furthermore this call is not thread safe, user needs to synchronize multiple calls.

    class MessageLite

    #include <google/protobuf/message_lite.h>
    namespace google::protobuf

    Interface to light weight protocol messages.

    This interface is implemented by all protocol message objects. Non-lite messages additionally implement the Message interface, which is a subclass of MessageLite. Use MessageLite instead when you only need the subset of features which it supports – namely, nothing that uses descriptors or reflection. You can instruct the protocol compiler to generate classes which implement only MessageLite, not the full Message interface, by adding the following line to the .proto file:

    option optimize_for = LITE_RUNTIME;
    -

    This is particularly useful on resource-constrained systems where the full protocol buffers runtime library is too big.

    +

    This is particularly useful on resource-constrained systems where the full Protobuf runtime library is too big.

    -

    Note that on non-constrained systems (e.g. servers) when you need to link in lots of protocol definitions, a better way to reduce total code footprint is to use optimize_for = CODE_SIZE. This will make the generated code smaller while still supporting all the same features (at the expense of speed). optimize_for = LITE_RUNTIME is best when you only have a small number of message types linked into your binary, in which case the size of the protocol buffers runtime itself is the biggest problem.

    +

    Note that on non-constrained systems (e.g. servers) when you need to link in lots of protocol definitions, a better way to reduce total code footprint is to use optimize_for = CODE_SIZE. This will make the generated code smaller while still supporting all the same features (at the expense of speed). optimize_for = LITE_RUNTIME is best when you only have a small number of message types linked into your binary, in which case the size of the Protobuf runtime itself is the biggest problem.

    Users must not derive from this class. Only the protocol compiler and the internal library are allowed to create subclasses.

    Known subclasses:

    Members

    enum
    ParseFlags
    protected internal::InternalMetadata
    _internal_metadata_
    constexpr
    MessageLite()
    virtual
    ~MessageLite()
    template bool
    ParseFrom(const T & input)
    virtual uint8 *
    _InternalSerialize(uint8 * ptr, io::EpsCopyOutputStream * stream) const = 0
    Fast path when conditions match (ie. more...
    bool
    IsInitializedWithErrors() const
    Identical to IsInitialized() except that it logs an error message.
    protected template static T *
    CreateMaybeMessage(Arena * arena)
    protected explicit
    MessageLite(Arena * arena)
    protected Arena *
    GetOwningArena() const
    Returns the arena, if any, that directly owns this message and its internal memory (Arena::Own is different in that the arena doesn't directly own the internal memory). more...
    protected Arena *
    GetArenaForAllocation() const
    Returns the arena, used for allocating internal objects(e.g., child messages, etc), or owning incoming objects (e.g., set allocated).

    Basic Operations

    virtual std::string
    GetTypeName() const = 0
    Get the name of this message type, e.g. "foo.bar.BazProto".
    virtual MessageLite *
    New() const = 0
    Construct a new instance of the same type. more...
    virtual MessageLite *
    New(Arena * arena) const
    Construct a new instance on the arena. more...
    Arena *
    GetArena() const
    Same as GetOwningArena.
    void *
    GetMaybeArenaPointer() const
    Get a pointer that may be equal to this message's arena, or may not be. more...
    virtual void
    Clear() = 0
    Clear all fields of the message and set them to their default values. more...
    virtual bool
    IsInitialized() const = 0
    Quickly check if all required fields have values set.
    virtual std::string
    InitializationErrorString() const
    This is not implemented for Lite messages – it just returns "(cannot determine missing fields for lite message)". more...
    virtual void
    CheckTypeAndMergeFrom(const MessageLite & other) = 0
    If |other| is the exact same class as this, calls MergeFrom(). more...
    std::string
    DebugString() const
    These methods return a human-readable summary of the message. more...
    std::string
    ShortDebugString() const
    std::string
    Utf8DebugString() const
    MessageLite::DebugString is already Utf8 Safe. more...

    Parsing

    -

    Methods for parsing in protocol buffer format.

    +

    Methods for parsing in Protobuf format.

    Most of these are just simple wrappers around MergeFromCodedStream(). Clear() will be called before merging the input.

    -
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParseFromCodedStream(io::CodedInputStream * input)
    Fill the message with a protocol buffer parsed from the given input stream. more...
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParsePartialFromCodedStream(io::CodedInputStream * input)
    Like ParseFromCodedStream(), but accepts messages that are missing required fields.
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParseFromZeroCopyStream(io::ZeroCopyInputStream * input)
    Read a protocol buffer from the given zero-copy input stream. more...
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParsePartialFromZeroCopyStream(io::ZeroCopyInputStream * input)
    Like ParseFromZeroCopyStream(), but accepts messages that are missing required fields.
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParseFromFileDescriptor(int file_descriptor)
    Parse a protocol buffer from a file descriptor. more...
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParsePartialFromFileDescriptor(int file_descriptor)
    Like ParseFromFileDescriptor(), but accepts messages that are missing required fields.
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParseFromIstream(std::istream * input)
    Parse a protocol buffer from a C++ istream. more...
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParsePartialFromIstream(std::istream * input)
    Like ParseFromIstream(), but accepts messages that are missing required fields.
    bool
    MergePartialFromBoundedZeroCopyStream(io::ZeroCopyInputStream * input, int size)
    Read a protocol buffer from the given zero-copy input stream, expecting the message to be exactly "size" bytes long. more...
    bool
    MergeFromBoundedZeroCopyStream(io::ZeroCopyInputStream * input, int size)
    Like ParseFromBoundedZeroCopyStream(), but accepts messages that are missing required fields.
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParseFromBoundedZeroCopyStream(io::ZeroCopyInputStream * input, int size)
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParsePartialFromBoundedZeroCopyStream(io::ZeroCopyInputStream * input, int size)
    Like ParseFromBoundedZeroCopyStream(), but accepts messages that are missing required fields.
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParseFromString(ConstStringParam data)
    Parses a protocol buffer contained in a string. more...
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParsePartialFromString(ConstStringParam data)
    Like ParseFromString(), but accepts messages that are missing required fields.
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParseFromArray(const void * data, int size)
    Parse a protocol buffer contained in an array of bytes.
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParsePartialFromArray(const void * data, int size)
    Like ParseFromArray(), but accepts messages that are missing required fields.
    bool
    MergeFromCodedStream(io::CodedInputStream * input)
    Reads a protocol buffer from the stream and merges it into this Message. more...
    bool
    MergePartialFromCodedStream(io::CodedInputStream * input)
    Like MergeFromCodedStream(), but succeeds even if required fields are missing in the input. more...
    bool
    MergeFromString(ConstStringParam data)
    Merge a protocol buffer contained in a string.

    Serialization

    -

    Methods for serializing in protocol buffer format.

    +
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParseFromCodedStream(io::CodedInputStream * input)
    Fill the message with data parsed from the given input stream. more...
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParsePartialFromCodedStream(io::CodedInputStream * input)
    Like ParseFromCodedStream(), but accepts messages that are missing required fields.
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParseFromZeroCopyStream(io::ZeroCopyInputStream * input)
    Read a Protobuf message from the given zero-copy input stream. more...
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParsePartialFromZeroCopyStream(io::ZeroCopyInputStream * input)
    Like ParseFromZeroCopyStream(), but accepts messages that are missing required fields.
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParseFromFileDescriptor(int file_descriptor)
    Parse a Protobuf message from a file descriptor. more...
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParsePartialFromFileDescriptor(int file_descriptor)
    Like ParseFromFileDescriptor(), but accepts messages that are missing required fields.
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParseFromIstream(std::istream * input)
    Parse a Protobuf message from a C++ istream. more...
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParsePartialFromIstream(std::istream * input)
    Like ParseFromIstream(), but accepts messages that are missing required fields.
    bool
    MergePartialFromBoundedZeroCopyStream(io::ZeroCopyInputStream * input, int size)
    Read a Protobuf message from the given zero-copy input stream, expecting the message to be exactly "size" bytes long. more...
    bool
    MergeFromBoundedZeroCopyStream(io::ZeroCopyInputStream * input, int size)
    Like ParseFromBoundedZeroCopyStream(), but accepts messages that are missing required fields.
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParseFromBoundedZeroCopyStream(io::ZeroCopyInputStream * input, int size)
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParsePartialFromBoundedZeroCopyStream(io::ZeroCopyInputStream * input, int size)
    Like ParseFromBoundedZeroCopyStream(), but accepts messages that are missing required fields.
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParseFromString(ConstStringParam data)
    Parses a Protobuf message contained in a string. more...
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParsePartialFromString(ConstStringParam data)
    Like ParseFromString(), but accepts messages that are missing required fields.
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParseFromArray(const void * data, int size)
    Parse a Protobuf message contained in an array of bytes.
    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
    ParsePartialFromArray(const void * data, int size)
    Like ParseFromArray(), but accepts messages that are missing required fields.
    bool
    MergeFromCodedStream(io::CodedInputStream * input)
    Reads a Protobuf message from the stream and merges it into this Message. more...
    bool
    MergePartialFromCodedStream(io::CodedInputStream * input)
    Like MergeFromCodedStream(), but succeeds even if required fields are missing in the input. more...
    bool
    MergeFromString(ConstStringParam data)
    Merge a Protobuf message contained in a string.

    Serialization

    +

    Methods for serializing in Protobuf format.

    Most of these are just simple wrappers around ByteSize() and SerializeWithCachedSizes().

    -
    bool
    SerializeToCodedStream(io::CodedOutputStream * output) const
    Write a protocol buffer of this message to the given output. more...
    bool
    SerializePartialToCodedStream(io::CodedOutputStream * output) const
    Like SerializeToCodedStream(), but allows missing required fields.
    bool
    SerializeToZeroCopyStream(io::ZeroCopyOutputStream * output) const
    Write the message to the given zero-copy output stream. more...
    bool
    SerializePartialToZeroCopyStream(io::ZeroCopyOutputStream * output) const
    Like SerializeToZeroCopyStream(), but allows missing required fields.
    bool
    SerializeToString(std::string * output) const
    Serialize the message and store it in the given string. more...
    bool
    SerializePartialToString(std::string * output) const
    Like SerializeToString(), but allows missing required fields.
    bool
    SerializeToArray(void * data, int size) const
    Serialize the message and store it in the given byte array. more...
    bool
    SerializePartialToArray(void * data, int size) const
    Like SerializeToArray(), but allows missing required fields.
    std::string
    SerializeAsString() const
    Make a string encoding the message. more...
    std::string
    SerializePartialAsString() const
    Like SerializeAsString(), but allows missing required fields.
    bool
    SerializeToFileDescriptor(int file_descriptor) const
    Serialize the message and write it to the given file descriptor. more...
    bool
    SerializePartialToFileDescriptor(int file_descriptor) const
    Like SerializeToFileDescriptor(), but allows missing required fields.
    bool
    SerializeToOstream(std::ostream * output) const
    Serialize the message and write it to the given C++ ostream. more...
    bool
    SerializePartialToOstream(std::ostream * output) const
    Like SerializeToOstream(), but allows missing required fields.
    bool
    AppendToString(std::string * output) const
    Like SerializeToString(), but appends to the data to the string's existing contents. more...
    bool
    AppendPartialToString(std::string * output) const
    Like AppendToString(), but allows missing required fields.
    virtual size_t
    ByteSizeLong() const = 0
    Computes the serialized size of the message. more...
    int
    ByteSize() const
    Legacy ByteSize() API.
    void
    SerializeWithCachedSizes(io::CodedOutputStream * output) const
    Serializes the message without recomputing the size. more...
    uint8 *
    SerializeWithCachedSizesToArray(uint8 * target) const
    Like SerializeWithCachedSizes, but writes directly to *target, returning a pointer to the byte immediately after the last byte written. more...
    virtual int
    GetCachedSize() const = 0
    Returns the result of the last call to ByteSize(). more...
    virtual const char *
    _InternalParse(const char * , internal::ParseContext * )

    enum MessageLite::ParseFlags {
      kMerge = = 0,
      kParse = = 1,
      kMergePartial = = 2,
      kParsePartial = = 3,
      kMergeWithAliasing = = 4,
      kParseWithAliasing = = 5,
      kMergePartialWithAliasing = = 6,
      kParsePartialWithAliasing = = 7
    }

    kMerge
    kParse
    kMergePartial
    kParsePartial
    kMergeWithAliasing
    kParseWithAliasing
    kMergePartialWithAliasing
    kParsePartialWithAliasing

    virtual uint8 * MessageLite::_InternalSerialize(
            uint8 * ptr,
            io::EpsCopyOutputStream * stream) const = 0

    Fast path when conditions match (ie.

    non-deterministic) uint8* _InternalSerialize(uint8* ptr) const;

    +
    bool
    SerializeToCodedStream(io::CodedOutputStream * output) const
    Write this Protobuf message to the given output. more...
    bool
    SerializePartialToCodedStream(io::CodedOutputStream * output) const
    Like SerializeToCodedStream(), but allows missing required fields.
    bool
    SerializeToZeroCopyStream(io::ZeroCopyOutputStream * output) const
    Write the message to the given zero-copy output stream. more...
    bool
    SerializePartialToZeroCopyStream(io::ZeroCopyOutputStream * output) const
    Like SerializeToZeroCopyStream(), but allows missing required fields.
    bool
    SerializeToString(std::string * output) const
    Serialize the message and store it in the given string. more...
    bool
    SerializePartialToString(std::string * output) const
    Like SerializeToString(), but allows missing required fields.
    bool
    SerializeToArray(void * data, int size) const
    Serialize the message and store it in the given byte array. more...
    bool
    SerializePartialToArray(void * data, int size) const
    Like SerializeToArray(), but allows missing required fields.
    std::string
    SerializeAsString() const
    Make a string encoding the message. more...
    std::string
    SerializePartialAsString() const
    Like SerializeAsString(), but allows missing required fields.
    bool
    SerializeToFileDescriptor(int file_descriptor) const
    Serialize the message and write it to the given file descriptor. more...
    bool
    SerializePartialToFileDescriptor(int file_descriptor) const
    Like SerializeToFileDescriptor(), but allows missing required fields.
    bool
    SerializeToOstream(std::ostream * output) const
    Serialize the message and write it to the given C++ ostream. more...
    bool
    SerializePartialToOstream(std::ostream * output) const
    Like SerializeToOstream(), but allows missing required fields.
    bool
    AppendToString(std::string * output) const
    Like SerializeToString(), but appends to the data to the string's existing contents. more...
    bool
    AppendPartialToString(std::string * output) const
    Like AppendToString(), but allows missing required fields.
    virtual size_t
    ByteSizeLong() const = 0
    Computes the serialized size of the message. more...
    int
    ByteSize() const
    Legacy ByteSize() API.
    void
    SerializeWithCachedSizes(io::CodedOutputStream * output) const
    Serializes the message without recomputing the size. more...
    uint8 *
    SerializeWithCachedSizesToArray(uint8 * target) const
    Like SerializeWithCachedSizes, but writes directly to *target, returning a pointer to the byte immediately after the last byte written. more...
    virtual int
    GetCachedSize() const = 0
    Returns the result of the last call to ByteSize(). more...
    virtual const char *
    _InternalParse(const char * , internal::ParseContext * )

    enum MessageLite::ParseFlags {
      kMerge = = 0,
      kParse = = 1,
      kMergePartial = = 2,
      kParsePartial = = 3,
      kMergeWithAliasing = = 4,
      kParseWithAliasing = = 5,
      kMergePartialWithAliasing = = 6,
      kParsePartialWithAliasing = = 7
    }

    kMerge
    kParse
    kMergePartial
    kParsePartial
    kMergeWithAliasing
    kParseWithAliasing
    kMergePartialWithAliasing
    kParsePartialWithAliasing

    virtual uint8 * MessageLite::_InternalSerialize(
            uint8 * ptr,
            io::EpsCopyOutputStream * stream) const = 0

    Fast path when conditions match (ie.

    non-deterministic) uint8* _InternalSerialize(uint8* ptr) const;

    protected Arena * MessageLite::GetOwningArena() const

    Returns the arena, if any, that directly owns this message and its internal memory (Arena::Own is different in that the arena doesn't directly own the internal memory).

    This method is used in proto's implementation for swapping, moving and setting allocated, for deciding whether the ownership of this message or its internal memory could be changed.

    virtual MessageLite * MessageLite::New() const = 0

    Construct a new instance of the same type.

    Ownership is passed to the caller.

    virtual MessageLite * MessageLite::New(
            Arena * arena) const

    Construct a new instance on the arena.

    Ownership is passed to the caller if arena is a NULL. Default implementation for backwards compatibility.

    @@ -48,19 +48,19 @@ determine missing fields for lite message)".

    However, it is implemented f

    The format of the returned string is subject to change, so please do not assume it will remain stable over time.

    std::string MessageLite::Utf8DebugString() const

    MessageLite::DebugString is already Utf8 Safe.

    This is to add compatibility with Message.

    -

    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
        MessageLite::ParseFromCodedStream(
            io::CodedInputStream * input)

    Fill the message with a protocol buffer parsed from the given input stream.

    Returns false on a read error or if the input is in the wrong format. A successful return does not indicate the entire input is consumed, ensure you call ConsumedEntireMessage() to check that if applicable.

    -

    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
        MessageLite::ParseFromZeroCopyStream(
            io::ZeroCopyInputStream * input)

    Read a protocol buffer from the given zero-copy input stream.

    If successful, the entire input will be consumed.

    -

    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
        MessageLite::ParseFromFileDescriptor(
            int file_descriptor)

    Parse a protocol buffer from a file descriptor.

    If successful, the entire input will be consumed.

    -

    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
        MessageLite::ParseFromIstream(
            std::istream * input)

    Parse a protocol buffer from a C++ istream.

    If successful, the entire input will be consumed.

    -

    bool MessageLite::MergePartialFromBoundedZeroCopyStream(
            io::ZeroCopyInputStream * input,
            int size)

    Read a protocol buffer from the given zero-copy input stream, expecting the message to be exactly "size" bytes long.

    If successful, exactly this many bytes will have been consumed from the input.

    -

    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
        MessageLite::ParseFromString(
            ConstStringParam data)

    Parses a protocol buffer contained in a string.

    Returns true on success. This function takes a string in the (non-human-readable) binary wire format, matching the encoding output by MessageLite::SerializeToString(). If you'd like to convert a human-readable string into a protocol buffer object, see google::protobuf::TextFormat::ParseFromString().

    -

    bool MessageLite::MergeFromCodedStream(
            io::CodedInputStream * input)

    Reads a protocol buffer from the stream and merges it into this Message.

    Singular fields read from the what is already in the Message and repeated fields are appended to those already present.

    +

    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
        MessageLite::ParseFromCodedStream(
            io::CodedInputStream * input)

    Fill the message with data parsed from the given input stream.

    Returns false on a read error or if the input is in the wrong format. A successful return does not indicate the entire input is consumed, ensure you call ConsumedEntireMessage() to check that if applicable.

    +

    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
        MessageLite::ParseFromZeroCopyStream(
            io::ZeroCopyInputStream * input)

    Read a Protobuf message from the given zero-copy input stream.

    If successful, the entire input will be consumed.

    +

    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
        MessageLite::ParseFromFileDescriptor(
            int file_descriptor)

    Parse a Protobuf message from a file descriptor.

    If successful, the entire input will be consumed.

    +

    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
        MessageLite::ParseFromIstream(
            std::istream * input)

    Parse a Protobuf message from a C++ istream.

    If successful, the entire input will be consumed.

    +

    bool MessageLite::MergePartialFromBoundedZeroCopyStream(
            io::ZeroCopyInputStream * input,
            int size)

    Read a Protobuf message from the given zero-copy input stream, expecting the message to be exactly "size" bytes long.

    If successful, exactly this many bytes will have been consumed from the input.

    +

    PROTOBUF_ATTRIBUTE_REINITIALIZES bool
        MessageLite::ParseFromString(
            ConstStringParam data)

    Parses a Protobuf message contained in a string.

    Returns true on success. This function takes a string in the (non-human-readable) binary wire format, matching the encoding output by MessageLite::SerializeToString(). If you'd like to convert a human-readable string into a Protobuf object, see google::protobuf::TextFormat::ParseFromString().

    +

    bool MessageLite::MergeFromCodedStream(
            io::CodedInputStream * input)

    Reads a Protobuf message from the stream and merges it into this Message.

    Singular fields read from the what is already in the Message and repeated fields are appended to those already present.

    It is the responsibility of the caller to call input->LastTagWas() (for groups) or input->ConsumedEntireMessage() (for non-groups) after this returns to verify that the message's end was delimited correctly.

    ParseFromCodedStream() is implemented as Clear() followed by MergeFromCodedStream().

    bool MessageLite::MergePartialFromCodedStream(
            io::CodedInputStream * input)

    Like MergeFromCodedStream(), but succeeds even if required fields are missing in the input.

    MergeFromCodedStream() is just implemented as MergePartialFromCodedStream() followed by IsInitialized().

    -

    bool MessageLite::SerializeToCodedStream(
            io::CodedOutputStream * output) const

    Write a protocol buffer of this message to the given output.

    Returns false on a write error. If the message is missing required fields, this may GOOGLE_CHECK-fail.

    +

    bool MessageLite::SerializeToCodedStream(
            io::CodedOutputStream * output) const

    Write this Protobuf message to the given output.

    Returns false on a write error. If the message is missing required fields, this may GOOGLE_CHECK-fail.

    bool MessageLite::SerializeToZeroCopyStream(
            io::ZeroCopyOutputStream * output) const

    Write the message to the given zero-copy output stream.

    All required fields must be set.

    bool MessageLite::SerializeToString(
            std::string * output) const

    Serialize the message and store it in the given string.

    All required fields must be set.

    bool MessageLite::SerializeToArray(
            void * data,
            int size) const

    Serialize the message and store it in the given byte array.

    All required fields must be set.

    diff --git a/content/reference/cpp/api-docs/google.protobuf.repeated_field.md b/content/reference/cpp/api-docs/google.protobuf.repeated_field.md index 7dafc1aac..62824ecd2 100644 --- a/content/reference/cpp/api-docs/google.protobuf.repeated_field.md +++ b/content/reference/cpp/api-docs/google.protobuf.repeated_field.md @@ -2,11 +2,11 @@ title = "repeated_field.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ -

    #include <google/protobuf/repeated_field.h>
    namespace google::protobuf

    RepeatedField and RepeatedPtrField are used by generated protocol message classes to manipulate repeated fields.

    These classes are very similar to STL's vector, but include a number of optimizations found to be useful specifically in the case of Protocol Buffers. RepeatedPtrField is particularly different from STL vector as it manages ownership of the pointers that it contains.

    +

    #include <google/protobuf/repeated_field.h>
    namespace google::protobuf

    RepeatedField and RepeatedPtrField are used by generated protocol message classes to manipulate repeated fields.

    These classes are very similar to STL's vector, but include a number of optimizations found to be useful specifically in the case of Protobuf. RepeatedPtrField is particularly different from STL vector as it manages ownership of the pointers that it contains.

    Typically, clients should not need to access RepeatedField objects directly, but should instead use the accessor functions generated automatically by the protocol compiler.

    diff --git a/content/reference/cpp/api-docs/google.protobuf.service.md b/content/reference/cpp/api-docs/google.protobuf.service.md index dd36735e7..e4d9b0070 100644 --- a/content/reference/cpp/api-docs/google.protobuf.service.md +++ b/content/reference/cpp/api-docs/google.protobuf.service.md @@ -2,7 +2,7 @@ title = "service.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ @@ -83,7 +83,7 @@ service->CallMethod(method, *request, response, callback);
    virtual void
    SetFailed(const std::string & reason) = 0
    Causes Failed() to return true on the client side. more...
    virtual bool
    IsCanceled() const = 0
    If true, indicates that the client canceled the RPC, so the server may as well give up on replying to it. more...
    virtual void
    NotifyOnCancel(Closure * callback) = 0
    Asks that the given callback be called when the RPC is canceled. more...

    virtual void RpcController::Reset() = 0

    Resets the RpcController to its initial state so that it may be reused in a new call.

    Must not be called while an RPC is in progress.

    virtual bool RpcController::Failed() const = 0

    After a call has finished, returns true if the call failed.

    The possible reasons for failure depend on the RPC implementation. Failed() must not be called before a call has finished. If Failed() returns true, the contents of the response message are undefined.

    virtual void RpcController::StartCancel() = 0

    Advises the RPC system that the caller desires that the RPC call be canceled.

    The RPC system may cancel it immediately, may wait awhile and then cancel it, or may not even cancel the call at all. If the call is canceled, the "done" callback will still be called and the RpcController will indicate that the call failed at that time.

    -

    virtual void RpcController::SetFailed(
            const std::string & reason) = 0

    Causes Failed() to return true on the client side.

    "reason" will be incorporated into the message returned by ErrorText(). If you find you need to return machine-readable information about failures, you should incorporate it into your response protocol buffer and should NOT call SetFailed().

    +

    virtual void RpcController::SetFailed(
            const std::string & reason) = 0

    Causes Failed() to return true on the client side.

    "reason" will be incorporated into the message returned by ErrorText(). If you find you need to return machine-readable information about failures, you should incorporate it into your response Protobuf message and should NOT call SetFailed().

    virtual bool RpcController::IsCanceled() const = 0

    If true, indicates that the client canceled the RPC, so the server may as well give up on replying to it.

    The server should still call the final "done" callback.

    virtual void RpcController::NotifyOnCancel(
            Closure * callback) = 0

    Asks that the given callback be called when the RPC is canceled.

    The callback will always be called exactly once. If the RPC completes without being canceled, the callback will be called after completion. If the RPC has already been canceled when NotifyOnCancel() is called, the callback will be called immediately.

    NotifyOnCancel() must be called no more than once per request.

    diff --git a/content/reference/cpp/api-docs/google.protobuf.text_format.md b/content/reference/cpp/api-docs/google.protobuf.text_format.md index 26ae8cebb..f02945f34 100644 --- a/content/reference/cpp/api-docs/google.protobuf.text_format.md +++ b/content/reference/cpp/api-docs/google.protobuf.text_format.md @@ -2,11 +2,11 @@ title = "text_format.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ -

    #include <google/protobuf/text_format.h>
    namespace google::protobuf

    Utilities for printing and parsing protocol messages in a human-readable, text-based format.

    Classes in this file

    This class implements protocol buffer text format, colloquially known as text proto.
    The default printer that converts scalar values from fields into their string representation.
    Deprecated: please use FastFieldValuePrinter instead.
    Interface that Printers or Parsers can use to find extensions, or types referenced in Any messages.
    Data structure which is populated with the locations of each field value parsed from the text.
    A location in the parsed text.
    For more control over parsing, use this class.
    Class for those users which require more fine-grained control over how a protobuffer message is printed out.

    class TextFormat

    #include <google/protobuf/text_format.h>
    namespace google::protobuf

    This class implements protocol buffer text format, colloquially known as text proto.

    Printing and parsing protocol messages in text format is useful for debugging and human editing of messages.

    +

    #include <google/protobuf/text_format.h>
    namespace google::protobuf

    Utilities for printing and parsing protocol messages in a human-readable, text-based format.

    Classes in this file

    This class implements Protobuf text format, colloquially known as text proto.
    The default printer that converts scalar values from fields into their string representation.
    Deprecated: please use FastFieldValuePrinter instead.
    Interface that Printers or Parsers can use to find extensions, or types referenced in Any messages.
    Data structure which is populated with the locations of each field value parsed from the text.
    A location in the parsed text.
    For more control over parsing, use this class.
    Class for those users which require more fine-grained control over how a Protobuf message is printed out.

    class TextFormat

    #include <google/protobuf/text_format.h>
    namespace google::protobuf

    This class implements Protobuf text format, colloquially known as text proto.

    Printing and parsing protocol messages in text format is useful for debugging and human editing of messages.

    This class is really a namespace that contains only static methods.

    @@ -18,7 +18,7 @@ type = "docs"

    static bool TextFormat::Parse(
            io::ZeroCopyInputStream * input,
            Message * output)

    Parses a text-format protocol message from the given input stream to the given message object.

    This function parses the human-readable format written by Print(). Returns true on success. The message is cleared first, even if the function fails – See Merge() to avoid this behavior.

    Example input: "user {\n id: 123 extra { gender: MALE language: 'en' }\n}"

    One use for this function is parsing handwritten strings in test code. Another use is to parse the output from google::protobuf::Message::DebugString() (or ShortDebugString()), because these functions output using google::protobuf::TextFormat::Print().

    -

    If you would like to read a protocol buffer serialized in the (non-human-readable) binary wire format, see google::protobuf::MessageLite::ParseFromString().

    +

    If you would like to read a Protobuf message serialized in the (non-human-readable) binary wire format, see google::protobuf::MessageLite::ParseFromString().

    static bool TextFormat::ParseFieldValueFromString(
            const std::string & input,
            const FieldDescriptor * field,
            Message * message)

    Parse the given text as a single field value and store it into the given field of the given message.

    If the field is a repeated field, the new value will be added to the end

    class TextFormat::BaseTextGenerator

    #include <google/protobuf/text_format.h>
    namespace google::protobuf

    Members

    virtual
    ~BaseTextGenerator()
    virtual void
    Indent()
    virtual void
    Outdent()
    virtual size_t
    GetCurrentIndentationSize() const
    Returns the current indentation size in characters.
    virtual void
    Print(const char * text, size_t size) = 0
    Print text to the output stream.
    void
    PrintString(const std::string & str)
    template void
    PrintLiteral(const char(&) text)

    class TextFormat::FastFieldValuePrinter

    #include <google/protobuf/text_format.h>
    namespace google::protobuf

    The default printer that converts scalar values from fields into their string representation.

    You can derive from this FastFieldValuePrinter if you want to have fields to be printed in a different way and register it at the Printer.

    Members

    FastFieldValuePrinter()
    virtual
    ~FastFieldValuePrinter()
    virtual void
    PrintBool(bool val, BaseTextGenerator * generator) const
    virtual void
    PrintInt32(int32 val, BaseTextGenerator * generator) const
    virtual void
    PrintUInt32(uint32 val, BaseTextGenerator * generator) const
    virtual void
    PrintInt64(int64 val, BaseTextGenerator * generator) const
    virtual void
    PrintUInt64(uint64 val, BaseTextGenerator * generator) const
    virtual void
    PrintFloat(float val, BaseTextGenerator * generator) const
    virtual void
    PrintDouble(double val, BaseTextGenerator * generator) const
    virtual void
    PrintString(const std::string & val, BaseTextGenerator * generator) const
    virtual void
    PrintBytes(const std::string & val, BaseTextGenerator * generator) const
    virtual void
    PrintEnum(int32 val, const std::string & name, BaseTextGenerator * generator) const
    virtual void
    PrintFieldName(const Message & message, int field_index, int field_count, const Reflection * reflection, const FieldDescriptor * field, BaseTextGenerator * generator) const
    virtual void
    PrintFieldName(const Message & message, const Reflection * reflection, const FieldDescriptor * field, BaseTextGenerator * generator) const
    virtual void
    PrintMessageStart(const Message & message, int field_index, int field_count, bool single_line_mode, BaseTextGenerator * generator) const
    virtual bool
    PrintMessageContent(const Message & message, int field_index, int field_count, bool single_line_mode, BaseTextGenerator * generator) const
    Allows to override the logic on how to print the content of a message. more...
    virtual void
    PrintMessageEnd(const Message & message, int field_index, int field_count, bool single_line_mode, BaseTextGenerator * generator) const

    virtual bool FastFieldValuePrinter::PrintMessageContent(
            const Message & message,
            int field_index,
            int field_count,
            bool single_line_mode,
            BaseTextGenerator * generator) const

    Allows to override the logic on how to print the content of a message.

    Return false to use the default printing logic. Note that it is legal for this function to print something and then return false to use the default content printing (although at that point it would behave similarly to PrintMessageStart).

    @@ -35,12 +35,12 @@ type = "docs"

    void Parser::AllowUnknownExtension(
            bool allow)

    When an unknown extension is met, parsing will fail if this option is set to false (the default).

    If true, unknown extensions will be ignored and a warning message will be generated. Beware! Setting this option true may hide some errors (e.g. spelling error on extension name). This allows data loss; unlike binary format, text format cannot preserve unknown extensions. Avoid using this option if possible.

    void Parser::AllowUnknownField(
            bool allow)

    When an unknown field is met, parsing will fail if this option is set to false (the default).

    If true, unknown fields will be ignored and a warning message will be generated. Beware! Setting this option true may hide some errors (e.g. spelling error on field name). This allows data loss; unlike binary format, text format cannot preserve unknown fields. Avoid using this option if possible.

    void Parser::SetRecursionLimit(
            int limit)

    Sets maximum recursion depth which parser can use.

    This is effectively the maximum allowed nesting of proto messages.

    -

    class TextFormat::Printer

    #include <google/protobuf/text_format.h>
    namespace google::protobuf

    Class for those users which require more fine-grained control over how a protobuffer message is printed out.

    Members

    Printer()
    bool
    Print(const Message & message, io::ZeroCopyOutputStream * output) const
    bool
    PrintUnknownFields(const UnknownFieldSet & unknown_fields, io::ZeroCopyOutputStream * output) const
    bool
    PrintToString(const Message & message, std::string * output) const
    bool
    PrintUnknownFieldsToString(const UnknownFieldSet & unknown_fields, std::string * output) const
    void
    PrintFieldValueToString(const Message & message, const FieldDescriptor * field, int index, std::string * output) const
    void
    SetInitialIndentLevel(int indent_level)
    Adjust the initial indent level of all output. more...
    void
    SetSingleLineMode(bool single_line_mode)
    If printing in single line mode, then the entire message will be output on a single line with no line breaks.
    bool
    IsInSingleLineMode() const
    void
    SetUseFieldNumber(bool use_field_number)
    If use_field_number is true, uses field number instead of field name.
    void
    SetUseShortRepeatedPrimitives(bool use_short_repeated_primitives)
    Set true to print repeated primitives in a format like: more...
    void
    SetUseUtf8StringEscaping(bool as_utf8)
    Set true to output UTF-8 instead of ASCII. more...
    void
    SetDefaultFieldValuePrinter(const FastFieldValuePrinter * printer)
    Set the default FastFieldValuePrinter that is used for all fields that don't have a field-specific printer registered. more...
    void
    SetDefaultFieldValuePrinter(const FieldValuePrinter * printer)
    void
    SetHideUnknownFields(bool hide)
    Sets whether we want to hide unknown fields or not. more...
    void
    SetPrintMessageFieldsInIndexOrder(bool print_message_fields_in_index_order)
    If print_message_fields_in_index_order is true, fields of a proto message will be printed using the order defined in source code instead of the field number, extensions will be printed at the end of the message and their relative order is determined by the extension number. more...
    void
    SetExpandAny(bool expand)
    If expand==true, expand google.protobuf.Any payloads. more...
    void
    SetFinder(const Finder * finder)
    Set how parser finds message for Any payloads.
    void
    SetTruncateStringFieldLongerThan(const int64 truncate_string_field_longer_than)
    If non-zero, we truncate all string fields that are longer than this threshold. more...
    bool
    RegisterFieldValuePrinter(const FieldDescriptor * field, const FastFieldValuePrinter * printer)
    Register a custom field-specific FastFieldValuePrinter for fields with a particular FieldDescriptor. more...
    bool
    RegisterFieldValuePrinter(const FieldDescriptor * field, const FieldValuePrinter * printer)
    bool
    RegisterMessagePrinter(const Descriptor * descriptor, const MessagePrinter * printer)
    Register a custom message-specific MessagePrinter for messages with a particular Descriptor. more...

    void Printer::SetInitialIndentLevel(
            int indent_level)

    Adjust the initial indent level of all output.

    Each indent level is equal to two spaces.

    +

    class TextFormat::Printer

    #include <google/protobuf/text_format.h>
    namespace google::protobuf

    Class for those users which require more fine-grained control over how a Protobuf message is printed out.

    Members

    Printer()
    bool
    Print(const Message & message, io::ZeroCopyOutputStream * output) const
    bool
    PrintUnknownFields(const UnknownFieldSet & unknown_fields, io::ZeroCopyOutputStream * output) const
    bool
    PrintToString(const Message & message, std::string * output) const
    bool
    PrintUnknownFieldsToString(const UnknownFieldSet & unknown_fields, std::string * output) const
    void
    PrintFieldValueToString(const Message & message, const FieldDescriptor * field, int index, std::string * output) const
    void
    SetInitialIndentLevel(int indent_level)
    Adjust the initial indent level of all output. more...
    void
    SetSingleLineMode(bool single_line_mode)
    If printing in single line mode, then the entire message will be output on a single line with no line breaks.
    bool
    IsInSingleLineMode() const
    void
    SetUseFieldNumber(bool use_field_number)
    If use_field_number is true, uses field number instead of field name.
    void
    SetUseShortRepeatedPrimitives(bool use_short_repeated_primitives)
    Set true to print repeated primitives in a format like: more...
    void
    SetUseUtf8StringEscaping(bool as_utf8)
    Set true to output UTF-8 instead of ASCII. more...
    void
    SetDefaultFieldValuePrinter(const FastFieldValuePrinter * printer)
    Set the default FastFieldValuePrinter that is used for all fields that don't have a field-specific printer registered. more...
    void
    SetDefaultFieldValuePrinter(const FieldValuePrinter * printer)
    void
    SetHideUnknownFields(bool hide)
    Sets whether we want to hide unknown fields or not. more...
    void
    SetPrintMessageFieldsInIndexOrder(bool print_message_fields_in_index_order)
    If print_message_fields_in_index_order is true, fields of a proto message will be printed using the order defined in source code instead of the field number, extensions will be printed at the end of the message and their relative order is determined by the extension number. more...
    void
    SetExpandAny(bool expand)
    If expand==true, expand google.protobuf.Any payloads. more...
    void
    SetFinder(const Finder * finder)
    Set how parser finds message for Any payloads.
    void
    SetTruncateStringFieldLongerThan(const int64 truncate_string_field_longer_than)
    If non-zero, we truncate all string fields that are longer than this threshold. more...
    bool
    RegisterFieldValuePrinter(const FieldDescriptor * field, const FastFieldValuePrinter * printer)
    Register a custom field-specific FastFieldValuePrinter for fields with a particular FieldDescriptor. more...
    bool
    RegisterFieldValuePrinter(const FieldDescriptor * field, const FieldValuePrinter * printer)
    bool
    RegisterMessagePrinter(const Descriptor * descriptor, const MessagePrinter * printer)
    Register a custom message-specific MessagePrinter for messages with a particular Descriptor. more...

    void Printer::SetInitialIndentLevel(
            int indent_level)

    Adjust the initial indent level of all output.

    Each indent level is equal to two spaces.

    void Printer::SetUseShortRepeatedPrimitives(
            bool use_short_repeated_primitives)

    Set true to print repeated primitives in a format like: 

    field_name: [1, 2, 3, 4]

    instead of printing each value on its own line. Short format applies only to primitive values – i.e. everything except strings and sub-messages/groups.

    void Printer::SetUseUtf8StringEscaping(
            bool as_utf8)

    Set true to output UTF-8 instead of ASCII.

    The only difference is that bytes >= 0x80 in string fields will not be escaped, because they are assumed to be part of UTF-8 multi-byte sequences. This will change the default FastFieldValuePrinter.

    void Printer::SetDefaultFieldValuePrinter(
            const FastFieldValuePrinter * printer)

    Set the default FastFieldValuePrinter that is used for all fields that don't have a field-specific printer registered.

    Takes ownership of the printer.

    -

    void Printer::SetHideUnknownFields(
            bool hide)

    Sets whether we want to hide unknown fields or not.

    Usually unknown fields are printed in a generic way that includes the tag number of the field instead of field name. However, sometimes it is useful to be able to print the message without unknown fields (e.g. for the python protobuf version to maintain consistency between its pure python and c++ implementations).

    +

    void Printer::SetHideUnknownFields(
            bool hide)

    Sets whether we want to hide unknown fields or not.

    Usually unknown fields are printed in a generic way that includes the tag number of the field instead of field name. However, sometimes it is useful to be able to print the message without unknown fields (e.g. for the python Protobuf version to maintain consistency between its pure python and c++ implementations).

    void Printer::SetPrintMessageFieldsInIndexOrder(
            bool print_message_fields_in_index_order)

    If print_message_fields_in_index_order is true, fields of a proto message will be printed using the order defined in source code instead of the field number, extensions will be printed at the end of the message and their relative order is determined by the extension number.

    By default, use the field number order.

    void Printer::SetExpandAny(
            bool expand)

    If expand==true, expand google.protobuf.Any payloads.

    The output will be of form 

    [type_url] { <value_printed_in_text> }
    diff --git a/content/reference/cpp/api-docs/google.protobuf.unknown_field_set.md b/content/reference/cpp/api-docs/google.protobuf.unknown_field_set.md index 8eb6e768f..7ebb4623b 100644 --- a/content/reference/cpp/api-docs/google.protobuf.unknown_field_set.md +++ b/content/reference/cpp/api-docs/google.protobuf.unknown_field_set.md @@ -4,7 +4,7 @@ title = "unknown_field_set.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ @@ -12,7 +12,7 @@ type = "docs"

    To get the UnknownFieldSet attached to any message, call Reflection::GetUnknownFields().

    -

    This class is necessarily tied to the protocol buffer wire format, unlike the Reflection interface which is independent of any serialization scheme.

    +

    This class is necessarily tied to the Protobuf wire format, unlike the Reflection interface which is independent of any serialization scheme.

    Members

    UnknownFieldSet()
    ~UnknownFieldSet()
    void
    Clear()
    Remove all fields.
    void
    ClearAndFreeMemory()
    Remove all fields and deallocate internal data objects.
    bool
    empty() const
    Is this set empty?
    void
    MergeFrom(const UnknownFieldSet & other)
    Merge the contents of some other UnknownFieldSet with this one.
    void
    MergeFromAndDestroy(UnknownFieldSet * other)
    Similar to above, but this function will destroy the contents of other.
    void
    Swap(UnknownFieldSet * x)
    Swaps the contents of some other UnknownFieldSet with this one.
    size_t
    SpaceUsedExcludingSelfLong() const
    Computes (an estimate of) the total number of bytes currently used for storing the unknown fields in memory. more...
    int
    SpaceUsedExcludingSelf() const
    size_t
    SpaceUsedLong() const
    Version of SpaceUsed() including sizeof(*this).
    int
    SpaceUsed() const
    int
    field_count() const
    Returns the number of fields present in the UnknownFieldSet.
    const UnknownField &
    field(int index) const
    Get a field in the set, where 0 <= index < field_count(). more...
    UnknownField *
    mutable_field(int index)
    Get a mutable pointer to a field in the set, where 0 <= index < field_count(). more...
    static void
    MergeToInternalMetadata(const UnknownFieldSet & other, internal::InternalMetadata * metadata)
    Merge the contents an UnknownFieldSet with the UnknownFieldSet in *metadata, if there is one. more...

    Adding fields

    void
    AddVarint(int number, uint64 value)
    void
    AddFixed32(int number, uint32 value)
    void
    AddFixed64(int number, uint64 value)
    void
    AddLengthDelimited(int number, const std::string & value)
    std::string *
    AddLengthDelimited(int number)
    UnknownFieldSet *
    AddGroup(int number)
    void
    AddField(const UnknownField & field)
    Adds an unknown field from another set.
    void
    DeleteSubrange(int start, int num)
    Delete fields with indices in the range [start . more...
    void
    DeleteByNumber(int number)
    Delete all fields with a specific field number. more...

    Parsing helpers

    These work exactly like the similarly-named methods of Message.
    bool
    MergeFromCodedStream(io::CodedInputStream * input)
    bool
    ParseFromCodedStream(io::CodedInputStream * input)
    bool
    ParseFromZeroCopyStream(io::ZeroCopyInputStream * input)
    bool
    ParseFromArray(const void * data, int size)
    bool
    ParseFromString(const std::string & data)
    template bool
    MergeFromMessage(const MessageType & message)
    Merges this message's unknown field data (if any). more...
    static const UnknownFieldSet &
    default_instance()

    size_t UnknownFieldSet::SpaceUsedExcludingSelfLong() const

    Computes (an estimate of) the total number of bytes currently used for storing the unknown fields in memory.

    Does NOT include sizeof(*this) in the calculation.

    const UnknownField &
        UnknownFieldSet::field(
            int index) const

    Get a field in the set, where 0 <= index < field_count().

    The fields appear in the order in which they were added.

    diff --git a/content/reference/cpp/api-docs/google.protobuf.util.field_comparator.md b/content/reference/cpp/api-docs/google.protobuf.util.field_comparator.md index af327e911..2e031bbe1 100644 --- a/content/reference/cpp/api-docs/google.protobuf.util.field_comparator.md +++ b/content/reference/cpp/api-docs/google.protobuf.util.field_comparator.md @@ -4,16 +4,16 @@ title = "field_comparator.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ -

    #include <google/protobuf/util/field_comparator.h>
    namespace google::protobuf::util

    Defines classes for field comparison.

    Classes in this file

    Base class specifying the interface for comparing protocol buffer fields.
    Basic implementation of FieldComparator.

    class FieldComparator

    #include <google/protobuf/util/field_comparator.h>
    namespace google::protobuf::util

    Base class specifying the interface for comparing protocol buffer fields.

    Regular users should consider using or subclassing DefaultFieldComparator rather than this interface. Currently, this does not support comparing unknown fields.

    +

    #include <google/protobuf/util/field_comparator.h>
    namespace google::protobuf::util

    Defines classes for field comparison.

    Classes in this file

    Base class specifying the interface for comparing Protobuf fields.
    Basic implementation of FieldComparator.

    class FieldComparator

    #include <google/protobuf/util/field_comparator.h>
    namespace google::protobuf::util

    Base class specifying the interface for comparing Protobuf fields.

    Regular users should consider using or subclassing DefaultFieldComparator rather than this interface. Currently, this does not support comparing unknown fields.

    -

    Known subclasses:

    Members

    enum
    ComparisonResult
    FieldComparator()
    virtual
    ~FieldComparator()
    virtual ComparisonResult
    Compare(const Message & message_1, const Message & message_2, const FieldDescriptor * field, int index_1, int index_2, const util::FieldContext * field_context) = 0
    Compares the values of a field in two protocol buffer messages. more...

    enum FieldComparator::ComparisonResult {
      SAME,
      DIFFERENT,
      RECURSE
    }

    SAME

    Compared fields are equal.

    In case of comparing submessages, user should not recursively compare their contents.

    +

    Known subclasses:

    Members

    enum
    ComparisonResult
    FieldComparator()
    virtual
    ~FieldComparator()
    virtual ComparisonResult
    Compare(const Message & message_1, const Message & message_2, const FieldDescriptor * field, int index_1, int index_2, const util::FieldContext * field_context) = 0
    Compares the values of a field in two Protobuf messages. more...

    enum FieldComparator::ComparisonResult {
      SAME,
      DIFFERENT,
      RECURSE
    }

    SAME

    Compared fields are equal.

    In case of comparing submessages, user should not recursively compare their contents.

    DIFFERENT

    Compared fields are different.

    In case of comparing submessages, user should not recursively compare their contents.

    RECURSE

    Compared submessages need to be compared recursively.

    FieldComparator does not specify the semantics of recursive comparison. This value should not be returned for simple values.

    -

    virtual ComparisonResult FieldComparator::Compare(
            const Message & message_1,
            const Message & message_2,
            const FieldDescriptor * field,
            int index_1,
            int index_2,
            const util::FieldContext * field_context) = 0

    Compares the values of a field in two protocol buffer messages.

    Returns SAME or DIFFERENT for simple values, and SAME, DIFFERENT or RECURSE for submessages. Returning RECURSE for fields not being submessages is illegal. In case the given FieldDescriptor points to a repeated field, the indices need to be valid. Otherwise they should be ignored.

    +

    virtual ComparisonResult FieldComparator::Compare(
            const Message & message_1,
            const Message & message_2,
            const FieldDescriptor * field,
            int index_1,
            int index_2,
            const util::FieldContext * field_context) = 0

    Compares the values of a field in two Protobuf messages.

    Returns SAME or DIFFERENT for simple values, and SAME, DIFFERENT or RECURSE for submessages. Returning RECURSE for fields not being submessages is illegal. In case the given FieldDescriptor points to a repeated field, the indices need to be valid. Otherwise they should be ignored.

    FieldContext contains information about the specific instances of the fields being compared, versus FieldDescriptor which only contains general type information about the fields.

    class SimpleFieldComparator: public FieldComparator

    #include <google/protobuf/util/field_comparator.h>
    namespace google::protobuf::util

    Basic implementation of FieldComparator.

    Supports three modes of floating point value comparison: exact, approximate using MathUtil::AlmostEqual method, and arbitrarily precise using MathUtil::WithinFractionOrMargin.

    @@ -31,7 +31,7 @@ type = "docs"

    REQUIRES: float_comparison_ == APPROXIMATE

    protected ComparisonResult SimpleFieldComparator::SimpleCompare(
            const Message & message_1,
            const Message & message_2,
            const FieldDescriptor * field,
            int index_1,
            int index_2,
            const util::FieldContext * field_context)

    Returns the comparison result for the given field in two messages.

    This function is called directly by DefaultFieldComparator::Compare. Subclasses can call this function to compare fields they do not need to handle specially.

    protected bool SimpleFieldComparator::CompareWithDifferencer(
            MessageDifferencer * differencer,
            const Message & message1,
            const Message & message2,
            const util::FieldContext * field_context)

    Compare using the provided message_differencer.

    For example, a subclass can use this method to compare some field in a certain way using the same message_differencer instance and the field context.

    -

    class DefaultFieldComparator: public SimpleFieldComparator

    #include <google/protobuf/util/field_comparator.h>
    namespace google::protobuf::util

    Members

    virtual ComparisonResult
    Compare(const Message & message_1, const Message & message_2, const FieldDescriptor * field, int index_1, int index_2, const util::FieldContext * field_context)
    Compares the values of a field in two protocol buffer messages. more...

    virtual ComparisonResult DefaultFieldComparator::Compare(
            const Message & message_1,
            const Message & message_2,
            const FieldDescriptor * field,
            int index_1,
            int index_2,
            const util::FieldContext * field_context)

    Compares the values of a field in two protocol buffer messages.

    Returns SAME or DIFFERENT for simple values, and SAME, DIFFERENT or RECURSE for submessages. Returning RECURSE for fields not being submessages is illegal. In case the given FieldDescriptor points to a repeated field, the indices need to be valid. Otherwise they should be ignored.

    +

    class DefaultFieldComparator: public SimpleFieldComparator

    #include <google/protobuf/util/field_comparator.h>
    namespace google::protobuf::util

    Members

    virtual ComparisonResult
    Compare(const Message & message_1, const Message & message_2, const FieldDescriptor * field, int index_1, int index_2, const util::FieldContext * field_context)
    Compares the values of a field in two Protobuf messages. more...

    virtual ComparisonResult DefaultFieldComparator::Compare(
            const Message & message_1,
            const Message & message_2,
            const FieldDescriptor * field,
            int index_1,
            int index_2,
            const util::FieldContext * field_context)

    Compares the values of a field in two Protobuf messages.

    Returns SAME or DIFFERENT for simple values, and SAME, DIFFERENT or RECURSE for submessages. Returning RECURSE for fields not being submessages is illegal. In case the given FieldDescriptor points to a repeated field, the indices need to be valid. Otherwise they should be ignored.

    FieldContext contains information about the specific instances of the fields being compared, versus FieldDescriptor which only contains general type information about the fields.

    diff --git a/content/reference/cpp/api-docs/google.protobuf.util.field_mask_util.md b/content/reference/cpp/api-docs/google.protobuf.util.field_mask_util.md index 9b85ebf1b..864385650 100644 --- a/content/reference/cpp/api-docs/google.protobuf.util.field_mask_util.md +++ b/content/reference/cpp/api-docs/google.protobuf.util.field_mask_util.md @@ -2,15 +2,15 @@ title = "field_mask_util.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ -

    #include <google/protobuf/util/field_mask_util.h>
    namespace google::protobuf::util

    Defines utilities for the FieldMask well known type.

    Classes in this file

    class FieldMaskUtil

    #include <google/protobuf/util/field_mask_util.h>
    namespace google::protobuf::util

    Members

    static std::string
    ToString(const FieldMask & mask)
    Converts FieldMask to/from string, formatted by separating each path with a comma (e.g., "foo_bar,baz.quz").
    static void
    FromString(StringPiece str, FieldMask * out)
    template static void
    FromFieldNumbers(const std::vector< int64_t > & field_numbers, FieldMask * out)
    Populates the FieldMask with the paths corresponding to the fields with the given numbers, after checking that all field numbers are valid.
    static bool
    ToJsonString(const FieldMask & mask, std::string * out)
    Converts FieldMask to/from string, formatted according to proto3 JSON spec for FieldMask (e.g., "fooBar,baz.quz"). more...
    static bool
    FromJsonString(StringPiece str, FieldMask * out)
    static bool
    GetFieldDescriptors(const Descriptor * descriptor, StringPiece path, std::vector< const FieldDescriptor * > * field_descriptors)
    Get the descriptors of the fields which the given path from the message descriptor traverses, if field_descriptors is not null. more...
    template static bool
    IsValidPath(StringPiece path)
    Checks whether the given path is valid for type T.
    template static bool
    IsValidFieldMask(const FieldMask & mask)
    Checks whether the given FieldMask is valid for type T.
    template static void
    AddPathToFieldMask(StringPiece path, FieldMask * mask)
    Adds a path to FieldMask after checking whether the given path is valid. more...
    template static FieldMask
    GetFieldMaskForAllFields()
    Creates a FieldMask with all fields of type T. more...
    template static void
    GetFieldMaskForAllFields(FieldMask * out)
    static void
    GetFieldMaskForAllFields(const Descriptor * descriptor, FieldMask * out)
    This flavor takes the protobuf type descriptor as an argument. more...
    static void
    ToCanonicalForm(const FieldMask & mask, FieldMask * out)
    Converts a FieldMask to the canonical form. more...
    static void
    Union(const FieldMask & mask1, const FieldMask & mask2, FieldMask * out)
    Creates an union of two FieldMasks.
    static void
    Intersect(const FieldMask & mask1, const FieldMask & mask2, FieldMask * out)
    Creates an intersection of two FieldMasks.
    template static void
    Subtract(const FieldMask & mask1, const FieldMask & mask2, FieldMask * out)
    Subtracts mask2 from mask1 base of type T.
    static void
    Subtract(const Descriptor * descriptor, const FieldMask & mask1, const FieldMask & mask2, FieldMask * out)
    This flavor takes the protobuf type descriptor as an argument. more...
    static bool
    IsPathInFieldMask(StringPiece path, const FieldMask & mask)
    Returns true if path is covered by the given FieldMask. more...
    static void
    MergeMessageTo(const Message & source, const FieldMask & mask, const MergeOptions & options, Message * destination)
    Merges fields specified in a FieldMask into another message.
    static bool
    TrimMessage(const FieldMask & mask, Message * message)
    Removes from 'message' any field that is not represented in the given FieldMask. more...
    static bool
    TrimMessage(const FieldMask & mask, Message * message, const TrimOptions & options)
    Removes from 'message' any field that is not represented in the given FieldMask with customized TrimOptions. more...

    static bool FieldMaskUtil::ToJsonString(
            const FieldMask & mask,
            std::string * out)

    Converts FieldMask to/from string, formatted according to proto3 JSON spec for FieldMask (e.g., "fooBar,baz.quz").

    If the field name is not style conforming (i.e., not snake_case when converted to string, or not camelCase when converted from string), the conversion will fail.

    +

    #include <google/protobuf/util/field_mask_util.h>
    namespace google::protobuf::util

    Defines utilities for the FieldMask well known type.

    Classes in this file

    class FieldMaskUtil

    #include <google/protobuf/util/field_mask_util.h>
    namespace google::protobuf::util

    Members

    static std::string
    ToString(const FieldMask & mask)
    Converts FieldMask to/from string, formatted by separating each path with a comma (e.g., "foo_bar,baz.quz").
    static void
    FromString(StringPiece str, FieldMask * out)
    template static void
    FromFieldNumbers(const std::vector< int64_t > & field_numbers, FieldMask * out)
    Populates the FieldMask with the paths corresponding to the fields with the given numbers, after checking that all field numbers are valid.
    static bool
    ToJsonString(const FieldMask & mask, std::string * out)
    Converts FieldMask to/from string, formatted according to proto3 JSON spec for FieldMask (e.g., "fooBar,baz.quz"). more...
    static bool
    FromJsonString(StringPiece str, FieldMask * out)
    static bool
    GetFieldDescriptors(const Descriptor * descriptor, StringPiece path, std::vector< const FieldDescriptor * > * field_descriptors)
    Get the descriptors of the fields which the given path from the message descriptor traverses, if field_descriptors is not null. more...
    template static bool
    IsValidPath(StringPiece path)
    Checks whether the given path is valid for type T.
    template static bool
    IsValidFieldMask(const FieldMask & mask)
    Checks whether the given FieldMask is valid for type T.
    template static void
    AddPathToFieldMask(StringPiece path, FieldMask * mask)
    Adds a path to FieldMask after checking whether the given path is valid. more...
    template static FieldMask
    GetFieldMaskForAllFields()
    Creates a FieldMask with all fields of type T. more...
    template static void
    GetFieldMaskForAllFields(FieldMask * out)
    static void
    GetFieldMaskForAllFields(const Descriptor * descriptor, FieldMask * out)
    This flavor takes the Protobuf type descriptor as an argument. more...
    static void
    ToCanonicalForm(const FieldMask & mask, FieldMask * out)
    Converts a FieldMask to the canonical form. more...
    static void
    Union(const FieldMask & mask1, const FieldMask & mask2, FieldMask * out)
    Creates an union of two FieldMasks.
    static void
    Intersect(const FieldMask & mask1, const FieldMask & mask2, FieldMask * out)
    Creates an intersection of two FieldMasks.
    template static void
    Subtract(const FieldMask & mask1, const FieldMask & mask2, FieldMask * out)
    Subtracts mask2 from mask1 base of type T.
    static void
    Subtract(const Descriptor * descriptor, const FieldMask & mask1, const FieldMask & mask2, FieldMask * out)
    This flavor takes the Protobuf type descriptor as an argument. more...
    static bool
    IsPathInFieldMask(StringPiece path, const FieldMask & mask)
    Returns true if path is covered by the given FieldMask. more...
    static void
    MergeMessageTo(const Message & source, const FieldMask & mask, const MergeOptions & options, Message * destination)
    Merges fields specified in a FieldMask into another message.
    static bool
    TrimMessage(const FieldMask & mask, Message * message)
    Removes from 'message' any field that is not represented in the given FieldMask. more...
    static bool
    TrimMessage(const FieldMask & mask, Message * message, const TrimOptions & options)
    Removes from 'message' any field that is not represented in the given FieldMask with customized TrimOptions. more...

    static bool FieldMaskUtil::ToJsonString(
            const FieldMask & mask,
            std::string * out)

    Converts FieldMask to/from string, formatted according to proto3 JSON spec for FieldMask (e.g., "fooBar,baz.quz").

    If the field name is not style conforming (i.e., not snake_case when converted to string, or not camelCase when converted from string), the conversion will fail.

    static bool FieldMaskUtil::GetFieldDescriptors(
            const Descriptor * descriptor,
            StringPiece path,
            std::vector< const FieldDescriptor * > * field_descriptors)

    Get the descriptors of the fields which the given path from the message descriptor traverses, if field_descriptors is not null.

    Return false if the path is not valid, and the content of field_descriptors is unspecified.

    template static void FieldMaskUtil::AddPathToFieldMask(
            StringPiece path,
            FieldMask * mask)

    Adds a path to FieldMask after checking whether the given path is valid.

    This method check-fails if the path is not a valid path for type T.

    template static FieldMask FieldMaskUtil::GetFieldMaskForAllFields()

    Creates a FieldMask with all fields of type T.

    This FieldMask only contains fields of T but not any sub-message fields.

    -

    static void FieldMaskUtil::GetFieldMaskForAllFields(
            const Descriptor * descriptor,
            FieldMask * out)

    This flavor takes the protobuf type descriptor as an argument.

    Useful when the type is not known at compile time.

    +

    static void FieldMaskUtil::GetFieldMaskForAllFields(
            const Descriptor * descriptor,
            FieldMask * out)

    This flavor takes the Protobuf type descriptor as an argument.

    Useful when the type is not known at compile time.

    static void FieldMaskUtil::ToCanonicalForm(
            const FieldMask & mask,
            FieldMask * out)

    Converts a FieldMask to the canonical form.

    It will: 

    1. Remove paths that are covered by another path. For example,
@@ -18,7 +18,7 @@ type = "docs"
    is also in the FieldMask.
 2. Sort all paths in alphabetical order.
    -

    static void FieldMaskUtil::Subtract(
            const Descriptor * descriptor,
            const FieldMask & mask1,
            const FieldMask & mask2,
            FieldMask * out)

    This flavor takes the protobuf type descriptor as an argument.

    Useful when the type is not known at compile time.

    +

    static void FieldMaskUtil::Subtract(
            const Descriptor * descriptor,
            const FieldMask & mask1,
            const FieldMask & mask2,
            FieldMask * out)

    This flavor takes the Protobuf type descriptor as an argument.

    Useful when the type is not known at compile time.

    static bool FieldMaskUtil::IsPathInFieldMask(
            StringPiece path,
            const FieldMask & mask)

    Returns true if path is covered by the given FieldMask.

    Note that path "foo.bar" covers all paths like "foo.bar.baz", "foo.bar.quz.x", etc. Also note that parent paths are not covered by explicit child path, i.e. "foo.bar" does NOT cover "foo", even if "bar" is the only child.

    static bool FieldMaskUtil::TrimMessage(
            const FieldMask & mask,
            Message * message)

    Removes from 'message' any field that is not represented in the given FieldMask.

    If the FieldMask is empty, does nothing. Returns true if the message is modified.

    static bool FieldMaskUtil::TrimMessage(
            const FieldMask & mask,
            Message * message,
            const TrimOptions & options)

    Removes from 'message' any field that is not represented in the given FieldMask with customized TrimOptions.

    If the FieldMask is empty, does nothing. Returns true if the message is modified.

    diff --git a/content/reference/cpp/api-docs/google.protobuf.util.json_util.md b/content/reference/cpp/api-docs/google.protobuf.util.json_util.md index 2e16994af..6e263658f 100644 --- a/content/reference/cpp/api-docs/google.protobuf.util.json_util.md +++ b/content/reference/cpp/api-docs/google.protobuf.util.json_util.md @@ -2,20 +2,20 @@ title = "json_util.h" toc_hide = "true" linkTitle = "C++" -description = "This section contains reference documentation for working with protocol buffer classes in C++." +description = "This section contains reference documentation for working with Protobuf classes in C++." type = "docs" +++ -

    #include <google/protobuf/util/json_util.h>
    namespace google::protobuf::util

    Utility functions to convert between protobuf binary format and proto3 JSON format.

    Classes in this file

    File Members

    These definitions are not part of any class.
    typedef
    JsonPrintOptions JsonOptions
    DEPRECATED. Use JsonPrintOptions instead.
    util::Status
    MessageToJsonString(const Message & message, std::string * output, const JsonOptions & options)
    Converts from protobuf message to JSON and appends it to |output|. more...
    util::Status
    MessageToJsonString(const Message & message, std::string * output)
    util::Status
    JsonStringToMessage(StringPiece input, Message * message, const JsonParseOptions & options)
    Converts from JSON to protobuf message. more...
    util::Status
    JsonStringToMessage(StringPiece input, Message * message)
    util::Status
    BinaryToJsonStream(TypeResolver * resolver, const std::string & type_url, io::ZeroCopyInputStream * binary_input, io::ZeroCopyOutputStream * json_output, const JsonPrintOptions & options)
    Converts protobuf binary data to JSON. more...
    util::Status
    BinaryToJsonStream(TypeResolver * resolver, const std::string & type_url, io::ZeroCopyInputStream * binary_input, io::ZeroCopyOutputStream * json_output)
    util::Status
    BinaryToJsonString(TypeResolver * resolver, const std::string & type_url, const std::string & binary_input, std::string * json_output, const JsonPrintOptions & options)
    util::Status
    BinaryToJsonString(TypeResolver * resolver, const std::string & type_url, const std::string & binary_input, std::string * json_output)
    util::Status
    JsonToBinaryStream(TypeResolver * resolver, const std::string & type_url, io::ZeroCopyInputStream * json_input, io::ZeroCopyOutputStream * binary_output, const JsonParseOptions & options)
    Converts JSON data to protobuf binary format. more...
    util::Status
    JsonToBinaryStream(TypeResolver * resolver, const std::string & type_url, io::ZeroCopyInputStream * json_input, io::ZeroCopyOutputStream * binary_output)
    util::Status
    JsonToBinaryString(TypeResolver * resolver, const std::string & type_url, StringPiece json_input, std::string * binary_output, const JsonParseOptions & options)
    util::Status
    JsonToBinaryString(TypeResolver * resolver, const std::string & type_url, StringPiece json_input, std::string * binary_output)

    util::Status util::MessageToJsonString(
            const Message & message,
            std::string * output,
            const JsonOptions & options)

    Converts from protobuf message to JSON and appends it to |output|.

    This is a simple wrapper of BinaryToJsonString(). It will use the DescriptorPool of the passed-in message to resolve Any types.

    -

    util::Status util::JsonStringToMessage(
            StringPiece input,
            Message * message,
            const JsonParseOptions & options)

    Converts from JSON to protobuf message.

    This is a simple wrapper of JsonStringToBinary(). It will use the DescriptorPool of the passed-in message to resolve Any types.

    -

    util::Status util::BinaryToJsonStream(
            TypeResolver * resolver,
            const std::string & type_url,
            io::ZeroCopyInputStream * binary_input,
            io::ZeroCopyOutputStream * json_output,
            const JsonPrintOptions & options)

    Converts protobuf binary data to JSON.

    The conversion will fail if:

    +

    #include <google/protobuf/util/json_util.h>
    namespace google::protobuf::util

    Utility functions to convert between Protobuf binary format and proto3 JSON format.

    Classes in this file

    File Members

    These definitions are not part of any class.
    typedef
    JsonPrintOptions JsonOptions
    DEPRECATED. Use JsonPrintOptions instead.
    util::Status
    MessageToJsonString(const Message & message, std::string * output, const JsonOptions & options)
    Converts from Protobuf message to JSON and appends it to |output|. more...
    util::Status
    MessageToJsonString(const Message & message, std::string * output)
    util::Status
    JsonStringToMessage(StringPiece input, Message * message, const JsonParseOptions & options)
    Converts from JSON to Protobuf message. more...
    util::Status
    JsonStringToMessage(StringPiece input, Message * message)
    util::Status
    BinaryToJsonStream(TypeResolver * resolver, const std::string & type_url, io::ZeroCopyInputStream * binary_input, io::ZeroCopyOutputStream * json_output, const JsonPrintOptions & options)
    Converts Protobuf binary data to JSON. more...
    util::Status
    BinaryToJsonStream(TypeResolver * resolver, const std::string & type_url, io::ZeroCopyInputStream * binary_input, io::ZeroCopyOutputStream * json_output)
    util::Status
    BinaryToJsonString(TypeResolver * resolver, const std::string & type_url, const std::string & binary_input, std::string * json_output, const JsonPrintOptions & options)
    util::Status
    BinaryToJsonString(TypeResolver * resolver, const std::string & type_url, const std::string & binary_input, std::string * json_output)
    util::Status
    JsonToBinaryStream(TypeResolver * resolver, const std::string & type_url, io::ZeroCopyInputStream * json_input, io::ZeroCopyOutputStream * binary_output, const JsonParseOptions & options)
    Converts JSON data to Protobuf binary format. more...
    util::Status
    JsonToBinaryStream(TypeResolver * resolver, const std::string & type_url, io::ZeroCopyInputStream * json_input, io::ZeroCopyOutputStream * binary_output)
    util::Status
    JsonToBinaryString(TypeResolver * resolver, const std::string & type_url, StringPiece json_input, std::string * binary_output, const JsonParseOptions & options)
    util::Status
    JsonToBinaryString(TypeResolver * resolver, const std::string & type_url, StringPiece json_input, std::string * binary_output)

    util::Status util::MessageToJsonString(
            const Message & message,
            std::string * output,
            const JsonOptions & options)

    Converts from Protobuf message to JSON and appends it to |output|.

    This is a simple wrapper of BinaryToJsonString(). It will use the DescriptorPool of the passed-in message to resolve Any types.

    +

    util::Status util::JsonStringToMessage(
            StringPiece input,
            Message * message,
            const JsonParseOptions & options)

    Converts from JSON to Protobuf message.

    This is a simple wrapper of JsonStringToBinary(). It will use the DescriptorPool of the passed-in message to resolve Any types.

    +

    util::Status util::BinaryToJsonStream(
            TypeResolver * resolver,
            const std::string & type_url,
            io::ZeroCopyInputStream * binary_input,
            io::ZeroCopyOutputStream * json_output,
            const JsonPrintOptions & options)

    Converts Protobuf binary data to JSON.

    The conversion will fail if: 

    1. TypeResolver fails to resolve a type.
-2. input is not valid protobuf wire format, or conflicts with the type
+2. input is not valid Protobuf wire format, or conflicts with the type
    information returned by TypeResolver.

    Note that unknown fields will be discarded silently.

    -

    util::Status util::JsonToBinaryStream(
            TypeResolver * resolver,
            const std::string & type_url,
            io::ZeroCopyInputStream * json_input,
            io::ZeroCopyOutputStream * binary_output,
            const JsonParseOptions & options)

    Converts JSON data to protobuf binary format.

    The conversion will fail if:

    +

    util::Status util::JsonToBinaryStream(
            TypeResolver * resolver,
            const std::string & type_url,
            io::ZeroCopyInputStream * json_input,
            io::ZeroCopyOutputStream * binary_output,
            const JsonParseOptions & options)

    Converts JSON data to Protobuf binary format.

    The conversion will fail if: 

    1. TypeResolver fails to resolve a type.
 2. input is not valid JSON format, or conflicts with the type
diff --git a/content/reference/cpp/api-docs/google.protobuf.util.message_differencer.md b/content/reference/cpp/api-docs/google.protobuf.util.message_differencer.md
index baaa1a7d1..37a80619f 100644
--- a/content/reference/cpp/api-docs/google.protobuf.util.message_differencer.md
+++ b/content/reference/cpp/api-docs/google.protobuf.util.message_differencer.md
@@ -4,7 +4,7 @@
 title = "message_differencer.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
@@ -21,7 +21,7 @@ type = "docs"
 
 
    Note on handling of google.protobuf.Any: MessageDifferencer automatically unpacks Any::value into a Message and compares its individual fields. Messages encoded in a repeated Any cannot be compared using TreatAsMap.
    
 
    Note on thread-safety: MessageDifferencer is not thread-safe. You need to guard it with a lock to use the same MessageDifferencer instance from multiple threads. Note that it's fine to call static comparison methods (like MessageDifferencer::Equals) concurrently, but it's not recommended for performance critical code as it leads to extra allocations. 
    
-
    Members
    enum
    MessageFieldComparison
    enum
    Scope
    enum
    FloatComparison
    DEPRECATED. Use FieldComparator::FloatComparison instead.  more...
    enum
    RepeatedFieldComparison
    DefaultFieldComparator *
    default_impl
    FieldComparator *
    base
    static bool
    Equals(const Message & message1, const Message & message2)
    Determines whether the supplied messages are equal.  more...
    static bool
    Equivalent(const Message & message1, const Message & message2)
    Determines whether the supplied messages are equivalent.  more...
    static bool
    ApproximatelyEquals(const Message & message1, const Message & message2)
    Determines whether the supplied messages are approximately equal.  more...
    static bool
    ApproximatelyEquivalent(const Message & message1, const Message & message2)
    Determines whether the supplied messages are approximately equivalent.  more...
    explicit 
    MessageDifferencer()
    To add a Reporter, construct default here, then use ReportDifferencesTo or ReportDifferencesToString. 
    ~MessageDifferencer()
    void
    TreatAsSet(const FieldDescriptor * field)
    The elements of the given repeated field will be treated as a set for diffing purposes, so different orderings of the same elements will be considered equal.  more...
    void
    TreatAsSmartSet(const FieldDescriptor * field)
    void
    TreatAsList(const FieldDescriptor * field)
    The elements of the given repeated field will be treated as a list for diffing purposes, so different orderings of the same elements will NOT be considered equal.  more...
    void
    TreatAsSmartList(const FieldDescriptor * field)
    Note that the complexity is similar to treating as SET. 
    void
    TreatAsMap(const FieldDescriptor * field, const FieldDescriptor * key)
    The elements of the given repeated field will be treated as a map for diffing purposes, with |key| being the map key.  more...
    void
    TreatAsMapWithMultipleFieldsAsKey(const FieldDescriptor * field, const std::vector< const FieldDescriptor * > & key_fields)
    Same as TreatAsMap except that this method will use multiple fields as the key in comparison.  more...
    void
    TreatAsMapWithMultipleFieldPathsAsKey(const FieldDescriptor * field, const std::vector< std::vector< const FieldDescriptor * > > & key_field_paths)
    Same as TreatAsMapWithMultipleFieldsAsKey, except that each of the field do not necessarily need to be a direct subfield.  more...
    void
    TreatAsMapUsingKeyComparator(const FieldDescriptor * field, const MapKeyComparator * key_comparator)
    Uses a custom MapKeyComparator to determine if two elements have the same key when comparing a repeated field as a map.  more...
    MapKeyComparator *
    CreateMultipleFieldsMapKeyComparator(const std::vector< std::vector< const FieldDescriptor * > > & key_field_paths)
    Initiates and returns a new instance of MultipleFieldsMapKeyComparator. 
    void
    AddIgnoreCriteria(IgnoreCriteria * ignore_criteria)
    Add a custom ignore criteria that is evaluated in addition to the ignored fields added with IgnoreField.  more...
    void
    IgnoreField(const FieldDescriptor * field)
    Indicates that any field with the given descriptor should be ignored for the purposes of comparing two messages.  more...
    void
    set_field_comparator(FieldComparator * comparator)
    Sets the field comparator used to determine differences between protocol buffer fields.  more...
    void
    SetFractionAndMargin(const FieldDescriptor * field, double fraction, double margin)
    DEPRECATED.  more...
    void
    set_message_field_comparison(MessageFieldComparison comparison)
    Sets the type of comparison (as defined in the MessageFieldComparison enumeration above) that is used by this differencer when determining how to compare fields in messages. 
    void
    set_report_matches(bool report_matches)
    Tells the differencer whether or not to report matches.  more...
    void
    set_report_moves(bool report_moves)
    Tells the differencer whether or not to report moves (in a set or map repeated field).  more...
    void
    set_report_ignores(bool report_ignores)
    Tells the differencer whether or not to report ignored values.  more...
    void
    set_scope(Scope scope)
    Sets the scope of the comparison (as defined in the Scope enumeration above) that is used by this differencer when determining which fields to compare between the messages. 
    Scope
    scope()
    Returns the current scope used by this differencer. 
    void
    set_float_comparison(FloatComparison comparison)
    DEPRECATED.  more...
    void
    set_repeated_field_comparison(RepeatedFieldComparison comparison)
    Sets the type of comparison for repeated field (as defined in the RepeatedFieldComparison enumeration above) that is used by this differencer when compare repeated fields in messages. 
    RepeatedFieldComparison
    repeated_field_comparison()
    Returns the current repeated field comparison used by this differencer. 
    bool
    Compare(const Message & message1, const Message & message2)
    Compares the two specified messages, returning true if they are the same, false otherwise.  more...
    bool
    CompareWithFields(const Message & message1, const Message & message2, const std::vector< const FieldDescriptor * > & message1_fields, const std::vector< const FieldDescriptor * > & message2_fields)
    Same as above, except comparing only the list of fields specified by the two vectors of FieldDescriptors. 
    void
    ReportDifferencesToString(std::string * output)
    Automatically creates a reporter that will output the differences found (if any) to the specified output string pointer.  more...
    void
    ReportDifferencesTo(Reporter * reporter)
    Tells the MessageDifferencer to report differences via the specified reporter.  more...
     
    enum MessageDifferencer::MessageFieldComparison {
      EQUAL,
      EQUIVALENT
    }
    EQUALFields must be present in both messages for the messages to be considered the same. 
    EQUIVALENT
    Fields with default values are considered set for comparison purposes even if not explicitly set in the messages themselves. 
    Unknown fields are ignored. 
    
+
    Members
    enum
    MessageFieldComparison
    enum
    Scope
    enum
    FloatComparison
    DEPRECATED. Use FieldComparator::FloatComparison instead.  more...
    enum
    RepeatedFieldComparison
    DefaultFieldComparator *
    default_impl
    FieldComparator *
    base
    static bool
    Equals(const Message & message1, const Message & message2)
    Determines whether the supplied messages are equal.  more...
    static bool
    Equivalent(const Message & message1, const Message & message2)
    Determines whether the supplied messages are equivalent.  more...
    static bool
    ApproximatelyEquals(const Message & message1, const Message & message2)
    Determines whether the supplied messages are approximately equal.  more...
    static bool
    ApproximatelyEquivalent(const Message & message1, const Message & message2)
    Determines whether the supplied messages are approximately equivalent.  more...
    explicit 
    MessageDifferencer()
    To add a Reporter, construct default here, then use ReportDifferencesTo or ReportDifferencesToString. 
    ~MessageDifferencer()
    void
    TreatAsSet(const FieldDescriptor * field)
    The elements of the given repeated field will be treated as a set for diffing purposes, so different orderings of the same elements will be considered equal.  more...
    void
    TreatAsSmartSet(const FieldDescriptor * field)
    void
    TreatAsList(const FieldDescriptor * field)
    The elements of the given repeated field will be treated as a list for diffing purposes, so different orderings of the same elements will NOT be considered equal.  more...
    void
    TreatAsSmartList(const FieldDescriptor * field)
    Note that the complexity is similar to treating as SET. 
    void
    TreatAsMap(const FieldDescriptor * field, const FieldDescriptor * key)
    The elements of the given repeated field will be treated as a map for diffing purposes, with |key| being the map key.  more...
    void
    TreatAsMapWithMultipleFieldsAsKey(const FieldDescriptor * field, const std::vector< const FieldDescriptor * > & key_fields)
    Same as TreatAsMap except that this method will use multiple fields as the key in comparison.  more...
    void
    TreatAsMapWithMultipleFieldPathsAsKey(const FieldDescriptor * field, const std::vector< std::vector< const FieldDescriptor * > > & key_field_paths)
    Same as TreatAsMapWithMultipleFieldsAsKey, except that each of the field do not necessarily need to be a direct subfield.  more...
    void
    TreatAsMapUsingKeyComparator(const FieldDescriptor * field, const MapKeyComparator * key_comparator)
    Uses a custom MapKeyComparator to determine if two elements have the same key when comparing a repeated field as a map.  more...
    MapKeyComparator *
    CreateMultipleFieldsMapKeyComparator(const std::vector< std::vector< const FieldDescriptor * > > & key_field_paths)
    Initiates and returns a new instance of MultipleFieldsMapKeyComparator. 
    void
    AddIgnoreCriteria(IgnoreCriteria * ignore_criteria)
    Add a custom ignore criteria that is evaluated in addition to the ignored fields added with IgnoreField.  more...
    void
    IgnoreField(const FieldDescriptor * field)
    Indicates that any field with the given descriptor should be ignored for the purposes of comparing two messages.  more...
    void
    set_field_comparator(FieldComparator * comparator)
    Sets the field comparator used to determine differences between Protobuf fields.  more...
    void
    SetFractionAndMargin(const FieldDescriptor * field, double fraction, double margin)
    DEPRECATED.  more...
    void
    set_message_field_comparison(MessageFieldComparison comparison)
    Sets the type of comparison (as defined in the MessageFieldComparison enumeration above) that is used by this differencer when determining how to compare fields in messages. 
    void
    set_report_matches(bool report_matches)
    Tells the differencer whether or not to report matches.  more...
    void
    set_report_moves(bool report_moves)
    Tells the differencer whether or not to report moves (in a set or map repeated field).  more...
    void
    set_report_ignores(bool report_ignores)
    Tells the differencer whether or not to report ignored values.  more...
    void
    set_scope(Scope scope)
    Sets the scope of the comparison (as defined in the Scope enumeration above) that is used by this differencer when determining which fields to compare between the messages. 
    Scope
    scope()
    Returns the current scope used by this differencer. 
    void
    set_float_comparison(FloatComparison comparison)
    DEPRECATED.  more...
    void
    set_repeated_field_comparison(RepeatedFieldComparison comparison)
    Sets the type of comparison for repeated field (as defined in the RepeatedFieldComparison enumeration above) that is used by this differencer when compare repeated fields in messages. 
    RepeatedFieldComparison
    repeated_field_comparison()
    Returns the current repeated field comparison used by this differencer. 
    bool
    Compare(const Message & message1, const Message & message2)
    Compares the two specified messages, returning true if they are the same, false otherwise.  more...
    bool
    CompareWithFields(const Message & message1, const Message & message2, const std::vector< const FieldDescriptor * > & message1_fields, const std::vector< const FieldDescriptor * > & message2_fields)
    Same as above, except comparing only the list of fields specified by the two vectors of FieldDescriptors. 
    void
    ReportDifferencesToString(std::string * output)
    Automatically creates a reporter that will output the differences found (if any) to the specified output string pointer.  more...
    void
    ReportDifferencesTo(Reporter * reporter)
    Tells the MessageDifferencer to report differences via the specified reporter.  more...
     
    enum MessageDifferencer::MessageFieldComparison {
      EQUAL,
      EQUIVALENT
    }
    EQUALFields must be present in both messages for the messages to be considered the same. 
    EQUIVALENT
    Fields with default values are considered set for comparison purposes even if not explicitly set in the messages themselves. 
    Unknown fields are ignored. 
    
 
     
    enum MessageDifferencer::Scope {
      FULL,
      PARTIAL
    }
    FULLAll fields of both messages are considered in the comparison. 
    PARTIALOnly fields present in the first message are considered; fields set only in the second message will be skipped during comparison. 
     
    enum MessageDifferencer::FloatComparison {
      EXACT,
      APPROXIMATE
    }
    DEPRECATED. Use FieldComparator::FloatComparison instead. 
    EXACTFloats and doubles are compared exactly. 
    APPROXIMATEFloats and doubles are compared using the MathUtil::AlmostEquals method. 
     
    enum MessageDifferencer::RepeatedFieldComparison {
      AS_LIST,
      AS_SET,
      AS_SMART_LIST,
      AS_SMART_SET
    }
    
-      
+      
@@ -1107,8 +1107,7 @@ The JSON representation for `NullValue` is JSON `null`.
 
 ## Option {#option}
 
-A protocol buffer option, which can be attached to a message, field,
-enumeration, etc.
+A Protobuf option, which can be attached to a message, field, enumeration, etc.
 
 
    AS_LIST
    Repeated fields are compared in order. 
    Differing values at the same index are reported using ReportModified(). If the repeated fields have different numbers of elements, the unpaired elements are reported using ReportAdded() or ReportDeleted(). 
    
 
    AS_SET
    Treat all the repeated fields as sets. 
    See TreatAsSet(), as below. 
    
 
    AS_SMART_LIST
    Similar to AS_SET, but preserve the order and find the longest matching sequence from the first matching element. 
    To use an optimal solution, call SetMatchIndicesForSmartListCallback() to pass it in. 
    
@@ -58,7 +58,7 @@ type = "docs"
  
    void MessageDifferencer::AddIgnoreCriteria(
            IgnoreCriteria * ignore_criteria)
    Add a custom ignore criteria that is evaluated in addition to the ignored fields added with IgnoreField. 
    Takes ownership of ignore_criteria. 
    
 
     
    void MessageDifferencer::IgnoreField(
            const FieldDescriptor * field)
    Indicates that any field with the given descriptor should be ignored for the purposes of comparing two messages. 
    This applies to fields nested in the message structure as well as top level ones. When the MessageDifferencer encounters an ignored field, ReportIgnored is called on the reporter, if one is specified.
    
 
    The only place where the field's 'ignored' status is not applied is when it is being used as a key in a field passed to TreatAsMap or is one of the fields passed to TreatAsMapWithMultipleFieldsAsKey. In this case it is compared in key matching but after that it's ignored in value comparison. 
    
-
     
    void MessageDifferencer::set_field_comparator(
            FieldComparator * comparator)
    Sets the field comparator used to determine differences between protocol buffer fields. 
    By default it's set to a DefaultFieldComparator instance. MessageDifferencer doesn't take ownership over the passed object. Note that this method must be called before Compare for the comparator to be used. 
    
+
     
    void MessageDifferencer::set_field_comparator(
            FieldComparator * comparator)
    Sets the field comparator used to determine differences between Protobuf fields. 
    By default it's set to a DefaultFieldComparator instance. MessageDifferencer doesn't take ownership over the passed object. Note that this method must be called before Compare for the comparator to be used. 
    
 
     
    void MessageDifferencer::SetFractionAndMargin(
            const FieldDescriptor * field,
            double fraction,
            double margin)
    DEPRECATED. 
    Pass a DefaultFieldComparator instance instead. Sets the fraction and margin for the float comparison of a given field. Uses MathUtil::WithinFractionOrMargin to compare the values. NOTE: this method does nothing if differencer's field comparator has been 
    
 
    set to a custom object.
    
 
    REQUIRES: field->cpp_type == FieldDescriptor::CPPTYPE_DOUBLE or 
    
diff --git a/content/reference/cpp/api-docs/google.protobuf.util.time_util.md b/content/reference/cpp/api-docs/google.protobuf.util.time_util.md
index fa98680de..e011d8788 100644
--- a/content/reference/cpp/api-docs/google.protobuf.util.time_util.md
+++ b/content/reference/cpp/api-docs/google.protobuf.util.time_util.md
@@ -2,7 +2,7 @@
 title = "time_util.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
diff --git a/content/reference/cpp/api-docs/google.protobuf.util.type_resolver.md b/content/reference/cpp/api-docs/google.protobuf.util.type_resolver.md
index 5d2070fca..4866f95f1 100644
--- a/content/reference/cpp/api-docs/google.protobuf.util.type_resolver.md
+++ b/content/reference/cpp/api-docs/google.protobuf.util.type_resolver.md
@@ -4,7 +4,7 @@
 title = "type_resolver.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
diff --git a/content/reference/cpp/api-docs/google.protobuf.util.type_resolver_util.md b/content/reference/cpp/api-docs/google.protobuf.util.type_resolver_util.md
index a6ed66cce..aea64a3d8 100644
--- a/content/reference/cpp/api-docs/google.protobuf.util.type_resolver_util.md
+++ b/content/reference/cpp/api-docs/google.protobuf.util.type_resolver_util.md
@@ -4,7 +4,7 @@
 title = "type_resolver_util.h"
 toc_hide = "true"
 linkTitle = "C++"
-description = "This section contains reference documentation for working with protocol buffer classes in C++."
+description = "This section contains reference documentation for working with Protobuf classes in C++."
 type = "docs"
 +++
 
diff --git a/content/reference/cpp/arenas.md b/content/reference/cpp/arenas.md
index d33927597..31f5afaaa 100644
--- a/content/reference/cpp/arenas.md
+++ b/content/reference/cpp/arenas.md
@@ -2,12 +2,13 @@
 title = "C++ Arena Allocation Guide"
 weight = 520
 linkTitle = "Arena Allocation Guide"
-description = "Arena allocation is a C++-only feature that helps you optimize your memory usage and improve performance when working with protocol buffers."
+description = "Arena allocation is a C++-only feature that helps you optimize your memory usage and improve performance when working with Protobuf."
 type = "docs"
 +++
 
-This page describes exactly what C++ code the protocol
-buffer compiler generates in addition to the code described in the
+This
+page describes exactly what C++ code the Protobuf compiler generates in addition
+to the code described in the
 [C++ Generated Code Guide](/reference/cpp/cpp-generated)
 when arena allocation is enabled. It assumes that you are familiar with the
 material in the
@@ -17,11 +18,11 @@ material in the
 ## Why Use Arena Allocation? {#why}
 
 Memory allocation and deallocation constitutes a significant fraction of CPU
-time spent in protocol buffers code. By default, protocol buffers performs heap
-allocations for each message object, each of its subobjects, and several field
-types, such as strings. These allocations occur in bulk when parsing a message
-and when building new messages in memory, and associated deallocations happen
-when messages and their subobject trees are freed.
+time spent in Protobuf code. By default, Protobuf performs heap allocations for
+each message object, each of its subobjects, and several field types, such as
+strings. These allocations occur in bulk when parsing a message and when
+building new messages in memory, and associated deallocations happen when
+messages and their subobject trees are freed.
 
 Arena-based allocation has been designed to reduce this performance cost. With
 arena allocation, new objects are allocated out of a large piece of preallocated
@@ -50,8 +51,8 @@ Operation             | Heap-allocated proto messages
 
 ## Getting Started {#gettingstarted}
 
-The protocol buffer compiler generates code for arena allocation for the
-messages in your file, as used in the following example.
+The Protobuf compiler generates code for arena allocation for the messages in
+your file, as used in the following example.
 
 ```cpp
 #include 
@@ -102,7 +103,7 @@ class. This class implements the following public methods.
     T> static T* Create(Arena* arena, args...)`
 
     *   If `T` is fully compatible[^footnote], then the method creates a new
-        protocol buffer object of type `T` and its subobjects on the arena.
+        Protobuf message object of type `T` and its subobjects on the arena.
 
         If `arena` is not NULL, the returned object is allocated on the arena,
         its internal storage and sub-types (if any) will be allocated on the
@@ -144,7 +145,7 @@ class. This class implements the following public methods.
     array is created on the arena.
 
 [^footnote]: What it takes to be a "fully compatible" type is internal to the
-    protobuf library, and should not be assumed to be reliable.
+    Protobuf library, and should not be assumed to be reliable.
 
 ### "Owned list" Methods {#owned-list}
 
@@ -164,7 +165,7 @@ itself is deleted
     not attempt to free the underlying memory of object. This method is useful
     when an object is embedded in arena-allocated storage but its destructor
     will not otherwise be called, for example because its containing class is a
-    protobuf message whose destructor won't be called, or because it was
+    Protobuf message whose destructor won't be called, or because it was
     manually constructed in a block allocated by `AllocateArray()`.
 
 ### Other Methods {#other-methods}
diff --git a/content/reference/cpp/cpp-generated.md b/content/reference/cpp/cpp-generated.md
index 32ba50ccd..f59ce21d1 100644
--- a/content/reference/cpp/cpp-generated.md
+++ b/content/reference/cpp/cpp-generated.md
@@ -2,7 +2,7 @@
 title = "C++ Generated Code Guide"
 weight = 510
 linkTitle = "Generated Code Guide"
-description = "Describes exactly what C++ code the protocol buffer compiler generates for any given protocol definition. "
+description = "Describes exactly what C++ code the Protobuf compiler generates for any given protocol definition. "
 type = "docs"
 +++
 
@@ -17,7 +17,7 @@ before reading this document.
 
 ## Compiler Invocation {#invocation}
 
-The protocol buffer compiler produces C++ output when invoked with the
+The Protobuf compiler produces C++ output when invoked with the
 `--cpp_out=` command-line flag. The parameter to the `--cpp_out=` option is the
 directory where you want the compiler to write your C++ output. The compiler
 creates a header file and an implementation file for each `.proto` file input.
@@ -62,8 +62,8 @@ Given a simple message declaration:
 message Foo {}
 ```
 
-The protocol buffer compiler generates a class called `Foo`, which publicly
-derives from
+The Protobuf compiler generates a class called `Foo`, which publicly derives
+from
 [`google::protobuf::Message`](/reference/cpp/api-docs/google.protobuf.message).
 The class is a concrete class; no pure-virtual methods are left unimplemented.
 Methods that are virtual in `Message` but not pure-virtual may or may not be
@@ -210,10 +210,10 @@ that declaration, you must identify it as `Foo_Bar`.
 
 ## Fields {#fields}
 
-In addition to the methods described in the previous section, the protocol
-buffer compiler generates a set of accessor methods for each field defined
-within the message in the `.proto` file. These methods are in
-lower-case/snake-case, such as `has_foo()` and `clear_foo()`.
+In addition to the methods described in the previous section, the Protobuf
+compiler generates a set of accessor methods for each field defined within the
+message in the `.proto` file. These methods are in lower-case/snake-case, such
+as `has_foo()` and `clear_foo()`.
 
 As well as accessor methods, the compiler generates an integer constant for each
 field containing its field number. The constant name is the letter `k`, followed
@@ -939,9 +939,9 @@ The compiler will generate the following accessor methods:
 
 A
 [`google::protobuf::Map`](/reference/cpp/api-docs/google.protobuf.map)
-is a special container type used in protocol buffers to store map fields. As you
-can see from its interface below, it uses a commonly-used subset of `std::map`
-and `std::unordered_map` methods.
+is a special container type used in Protobuf to store map fields. As you can see
+from its interface below, it uses a commonly-used subset of `std::map` and
+`std::unordered_map` methods.
 
 {{% alert title="Note" color="note" %}} These maps
 are
@@ -1131,9 +1131,8 @@ enum Foo {
 }
 ```
 
-The protocol buffer compiler will generate a C++ enum type called `Foo` with the
-same set of values. In addition, the compiler will generate the following
-functions:
+The Protobuf compiler will generate a C++ enum type called `Foo` with the same
+set of values. In addition, the compiler will generate the following functions:
 
 -   `const EnumDescriptor* Foo_descriptor()`: Returns the type's descriptor,
     which contains information about what values this enum type defines.
@@ -1176,7 +1175,7 @@ known fields are listed. This could lead to unexpected behavior, including data
 corruption and runtime crashes. **Always add a default case or explicitly call
 `Foo_IsValid(int)` outside of the switch to handle unknown enum values.**
 
-You can define an enum inside a message type. In this case, the protocol buffer
+You can define an enum inside a message type. In this case, the Protobuf
 compiler generates code that makes it appear that the enum type itself was
 declared nested inside the message's class. The `Foo_descriptor()` and
 `Foo_IsValid()` functions are declared as static methods. In reality, the enum
@@ -1204,7 +1203,7 @@ message Foo {
 }
 ```
 
-The protocol buffer compiler will generate some additional methods for `Foo`:
+The Protobuf compiler will generate some additional methods for `Foo`:
 `HasExtension()`, `ExtensionSize()`, `ClearExtension()`, `GetExtension()`,
 `SetExtension()`, `MutableExtension()`, `AddExtension()`,
 `SetAllocatedExtension()` and `ReleaseExtension()`. Each of these methods takes,
@@ -1225,8 +1224,8 @@ extend Foo {
 }
 ```
 
-For the singular extension field `bar`, the protocol buffer compiler generates
-an "extension identifier" called `bar`, which you can use with `Foo`'s extension
+For the singular extension field `bar`, the Protobuf compiler generates an
+"extension identifier" called `bar`, which you can use with `Foo`'s extension
 accessors to access this extension, like so:
 
 ```cpp
@@ -1285,9 +1284,9 @@ FillInMyBaz(baz);
 ## Arena Allocation {#arena}
 
 Arena allocation is a C++-only feature that helps you optimize your memory usage
-and improve performance when working with protocol buffers. Enabling arena
-allocation in your `.proto` adds additional code for working with arenas to your
-C++ generated code. You can find out more about the arena allocation API in the
+and improve performance when working with Protobuf. Enabling arena allocation in
+your `.proto` adds additional code for working with arenas to your C++ generated
+code. You can find out more about the arena allocation API in the
 [Arena Allocation Guide](/reference/cpp/arenas).
 
 ## Services {#service}
@@ -1298,11 +1297,11 @@ If the `.proto` file contains the following line:
 option cc_generic_services = true;
 ```
 
-then the protocol buffer compiler will generate code based on the service
-definitions found in the file as described in this section. However, the
-generated code may be undesirable as it is not tied to any particular RPC
-system, and thus requires more levels of indirection than code tailored to one
-system. If you do NOT want this code to be generated, add this line to the file:
+then the Protobuf compiler will generate code based on the service definitions
+found in the file as described in this section. However, the generated code may
+be undesirable as it is not tied to any particular RPC system, and thus requires
+more levels of indirection than code tailored to one system. If you do NOT want
+this code to be generated, add this line to the file:
 
 ```proto
 option cc_generic_services = false;
@@ -1319,8 +1318,8 @@ to generate code appropriate for the system. These plugins are likely to require
 that abstract services are disabled, so that they can generate their own classes
 of the same names.
 
-The remainder of this section describes what the protocol buffer compiler
-generates when abstract services are enabled.
+The remainder of this section describes what the Protobuf compiler generates
+when abstract services are enabled.
 
 ### Interface
 
@@ -1332,8 +1331,8 @@ service Foo {
 }
 ```
 
-The protocol buffer compiler will generate a class `Foo` to represent this
-service. `Foo` will have a virtual method for each method defined in the service
+The Protobuf compiler will generate a class `Foo` to represent this service.
+`Foo` will have a virtual method for each method defined in the service
 definition. In this case, the method `Bar` is defined as:
 
 ```cpp
@@ -1351,8 +1350,8 @@ indicating that the method is unimplemented, then invoke the `done` callback.
 When implementing your own service, you must subclass this generated service and
 implement its methods as appropriate.
 
-`Foo` subclasses the `Service` interface. The protocol buffer compiler
-automatically generates implementations of the methods of `Service` as follows:
+`Foo` subclasses the `Service` interface. The Protobuf compiler automatically
+generates implementations of the methods of `Service` as follows:
 
 -   `GetDescriptor`: Returns the service's
     [`ServiceDescriptor`](/reference/cpp/api-docs/google.protobuf.descriptor#ServiceDescriptor).
@@ -1371,8 +1370,8 @@ The following static method is also generated:
 
 ### Stub {#stub}
 
-The protocol buffer compiler also generates a "stub" implementation of every
-service interface, which is used by clients wishing to send requests to servers
+The Protobuf compiler also generates a "stub" implementation of every service
+interface, which is used by clients wishing to send requests to servers
 implementing the service. For the `Foo` service (described earlier), the stub
 implementation `Foo_Stub` will be defined. As with nested message types, a
 `typedef` is used so that `Foo_Stub` can also be referred to as `Foo::Stub`.
@@ -1392,7 +1391,7 @@ The stub additionally implements each of the service's methods as a wrapper
 around the channel. Calling one of the methods simply calls
 `channel->CallMethod()`.
 
-The Protocol Buffer library does not include an RPC implementation. However, it
+The Protobuf library does not include an RPC implementation. However, it
 includes all of the tools you need to hook up a generated service class to any
 arbitrary RPC implementation of your choice. You need only provide
 implementations of
@@ -1423,4 +1422,4 @@ appears in both the `.pb.cc` file and the `.pb.h` file unless otherwise noted.
 
 Do not generate code which relies on private class members declared by the
 standard code generator, as these implementation details may change in future
-versions of Protocol Buffers.
+versions of Protobuf.
diff --git a/content/reference/cpp/string-view.md b/content/reference/cpp/string-view.md
index da38053c0..59de82bae 100644
--- a/content/reference/cpp/string-view.md
+++ b/content/reference/cpp/string-view.md
@@ -6,7 +6,7 @@ type = "docs"
 +++
 
 C++ string field APIs that use `std::string` significantly constrain the
-internal protobuf implementation and its evolution. For example,
+internal Protobuf implementation and its evolution. For example,
 `mutable_string_field()` returns `std::string*` that forces us to use
 `std::string` to store the field. This complicates its interaction on arenas and
 we have to maintain arena donation states to track whether string payload
@@ -160,7 +160,7 @@ enum Foo {
 }
 ```
 
-The protocol buffer compiler, in addition to the `Foo` enum, will generate the
+The Protobuf compiler, in addition to the `Foo` enum, will generate the
 following new function in addition to the standard
 [generated code](/reference/cpp/cpp-generated#enum):
 
diff --git a/content/reference/csharp/_index.md b/content/reference/csharp/_index.md
index 9a01fbe58..ca4234f8c 100644
--- a/content/reference/csharp/_index.md
+++ b/content/reference/csharp/_index.md
@@ -2,6 +2,6 @@
 title = "C# Reference"
 weight = 540
 linkTitle = "C#"
-description = "Reference documentation for working with protocol buffer classes in C#"
+description = "Reference documentation for working with Protobuf classes in C#"
 type = "docs"
 +++
diff --git a/content/reference/csharp/csharp-generated.md b/content/reference/csharp/csharp-generated.md
index f0a55220a..8d2c8ca51 100644
--- a/content/reference/csharp/csharp-generated.md
+++ b/content/reference/csharp/csharp-generated.md
@@ -2,7 +2,7 @@
 title = "C# Generated Code Guide"
 weight = 550
 linkTitle = "Generated Code Guide"
-description = "Describes exactly what C# code the protocol buffer compiler generates for protocol definitions using editions syntax."
+description = "Describes exactly what C# code the Protobuf compiler generates for protocol definitions using editions syntax."
 type = "docs"
 +++
 
@@ -14,17 +14,17 @@ before reading this document.
 
 ## Compiler Invocation {#invocation}
 
-The protocol buffer compiler produces C\# output when invoked with the
-`--csharp_out` command-line flag. The parameter to the `--csharp_out` option is
-the directory where you want the compiler to write your C\# output, although
-depending on [other options](#compiler_options) the compiler may create
-subdirectories of the specified directory. The compiler creates a single source
-file for each `.proto` file input, defaulting to an extension of `.cs` but
-configurable via compiler options.
+The Protobuf compiler produces C\# output when invoked with the `--csharp_out`
+command-line flag. The parameter to the `--csharp_out` option is the directory
+where you want the compiler to write your C\# output, although depending on
+[other options](#compiler_options) the compiler may create subdirectories of the
+specified directory. The compiler creates a single source file for each `.proto`
+file input, defaulting to an extension of `.cs` but configurable via compiler
+options.
 
 ### C\#-specific Options {#compiler_options}
 
-You can provide further C\# options to the protocol buffer compiler using the
+You can provide further C\# options to the Protobuf compiler using the
 `--csharp_opt` command-line flag. The supported options are:
 
 -   **file\_extension**: Sets the file extension for generated code. This
@@ -42,13 +42,13 @@ You can provide further C\# options to the protocol buffer compiler using the
     ```
 
     where `player.proto` has a `csharp_namespace` option of `Example.Game` the
-    protocol buffer compiler generates a file `src/Game/Player.cs` being
-    created. This option would usually correspond with the **default namespace**
-    option in a C\# project in Visual Studio. If the option is specified but
-    with an empty value, the full C\# namespace as used in the generated file
-    will be used for the directory hierarchy. If the option is not specified at
-    all, the generated files are simply written into the directory specified by
-    `--csharp_out` without any hierarchy being created.
+    Protobuf compiler generates a file `src/Game/Player.cs`. This option would
+    usually correspond with the **default namespace** option in a C\# project in
+    Visual Studio. If the option is specified but with an empty value, the full
+    C\# namespace as used in the generated file will be used for the directory
+    hierarchy. If the option is not specified at all, the generated files are
+    simply written into the directory specified by `--csharp_out` without any
+    hierarchy being created.
 
 -   **internal\_access**: When this option is specified, the generator creates
     types with the `internal` access modifier instead of `public`.
@@ -103,8 +103,8 @@ descriptor class is placed in a nested `Proto` namespace to avoid colliding with
 the message.
 
 As an example of all of these rules, consider the `timestamp.proto` file which
-is provided as part of Protocol Buffers. A cut down version of `timestamp.proto`
-looks like this:
+is provided as part of Protobuf. A cut down version of `timestamp.proto` looks
+like this:
 
 ```proto
 edition = "2023";
@@ -143,8 +143,8 @@ Given a simple message declaration:
 message Foo {}
 ```
 
-The protocol buffer compiler generates a sealed, partial class called `Foo`,
-which implements the `IMessage` interface, as shown below with member
+The Protobuf compiler generates a sealed, partial class called `Foo`, which
+implements the `IMessage` interface, as shown below with member
 declarations. See the inline comments for more information.
 
 ```csharp
@@ -232,9 +232,9 @@ same name nested within the same class—and that would be invalid C\#.
 
 ## Fields
 
-The protocol buffer compiler generates a C\# property for each field defined
-within a message. The exact nature of the property depends on the nature of the
-field: its type, and whether it is singular, repeated, or a map field.
+The Protobuf compiler generates a C\# property for each field defined within a
+message. The exact nature of the property depends on the nature of the field:
+its type, and whether it is singular, repeated, or a map field.
 
 ### Singular Fields {#singular}
 
@@ -345,9 +345,9 @@ enum Color {
 }
 ```
 
-The protocol buffer compiler will generate a C\# enum type called `Color` with
-the same set of values. The names of the enum values are converted to make them
-more idiomatic for C\# developers:
+The Protobuf compiler will generate a C\# enum type called `Color` with the same
+set of values. The names of the enum values are converted to make them more
+idiomatic for C\# developers:
 
 -   If the original name starts with the upper-cased form of the enum name
     itself, that is removed
diff --git a/content/reference/dart/_index.md b/content/reference/dart/_index.md
index eefb1100b..72ae1070e 100644
--- a/content/reference/dart/_index.md
+++ b/content/reference/dart/_index.md
@@ -2,6 +2,6 @@
 title = "Dart Reference"
 weight = 570
 linkTitle = "Dart"
-description = "Reference documentation for working with protocol buffer classes in Dart"
+description = "Reference documentation for working with Protobuf classes in Dart"
 type = "docs"
 +++
diff --git a/content/reference/dart/dart-generated.md b/content/reference/dart/dart-generated.md
index ff94ca5cd..52e1e16da 100644
--- a/content/reference/dart/dart-generated.md
+++ b/content/reference/dart/dart-generated.md
@@ -2,12 +2,12 @@
 title = "Dart Generated Code"
 weight = 580
 linkTitle = "Generated Code"
-description = "Describes what Dart code the protocol buffer compiler generates for any given protocol definition."
+description = "Describes what Dart code the Protobuf compiler generates for any given protocol definition."
 type = "docs"
 +++
 
-Any differences between
-proto2, proto3, and editions generated code are highlighted - note that these
+Any differences between proto2,
+proto3, and editions generated code are highlighted - note that these
 differences are in the generated code as described in this document, not the
 base API, which are the same in both versions. You should read the
 [proto2 language guide](/programming-guides/proto2),
@@ -17,7 +17,7 @@ before reading this document.
 
 ## Compiler Invocation {#invocation}
 
-The protocol buffer compiler requires a
+The Protobuf compiler requires a
 [plugin to generate Dart](https://github.com/dart-lang/dart-protoc-plugin) code.
 Installing it following the
 [instructions](https://github.com/dart-lang/dart-protoc-plugin#how-to-build-and-use)
@@ -53,8 +53,8 @@ Given a simple message declaration:
 message Foo {}
 ```
 
-The protocol buffer compiler generates a class called `Foo`, which extends the
-class `GeneratedMessage`.
+The Protobuf compiler generates a class called `Foo`, which extends the class
+`GeneratedMessage`.
 
 The class `GeneratedMessage` defines methods that let you check, manipulate,
 read, or write the entire message. In addition to these methods, the `Foo` class
@@ -62,7 +62,7 @@ defines the following methods and constructors:
 
 -   `Foo()`: Default constructor. Creates an instance where all singular fields
     are unset and repeated fields are empty.
--   `Foo.fromBuffer(...)`: Creates a `Foo` from serialized protocol buffer data
+-   `Foo.fromBuffer(...)`: Creates a `Foo` from serialized Protobuf data
     representing the message.
 -   `Foo.fromJson(...)`: Creates a `Foo` from a JSON string encoding the
     message.
@@ -92,9 +92,9 @@ In this case, the compiler generates two classes: `Foo` and `Foo_Bar`.
 
 ## Fields
 
-In addition to the methods described in the previous section, the protocol
-buffer compiler generates accessor methods for each field defined within the
-message in the `.proto` file.
+In addition to the methods described in the previous section, the Protobuf
+compiler generates accessor methods for each field defined within the message in
+the `.proto` file.
 
 Note that the generated names always use camel-case naming, even if the field
 name in the `.proto` file uses lower-case with underscores
@@ -336,9 +336,9 @@ enum Color {
 }
 ```
 
-The protocol buffer compiler will generate a class called `Color`, which extends
-the `ProtobufEnum` class. The class will include a `static const Color` for each
-of the four values, as well as a `static const List` that contains the
+The Protobuf compiler will generate a class called `Color`, which extends the
+`ProtobufEnum` class. The class will include a `static const Color` for each of
+the four values, as well as a `static const List` that contains the
 values.
 
 ```dart
@@ -390,7 +390,7 @@ message Bar {
 }
 ```
 
-The protocol buffer compiler will generate a class called `Bar`, which extends
+The Protobuf compiler will generate a class called `Bar`, which extends
 `GeneratedMessage`, and a class called `Bar_Color`, which extends
 `ProtobufEnum`.
 
@@ -410,9 +410,9 @@ extend Foo {
 }
 ```
 
-The protocol buffer compiler will generate, in addition to the `Foo` class, a
-class `Foo_test` which will contain a `static Extension` for each extension
-field in the file along with a method for registering all the extensions in an
+The Protobuf compiler will generate, in addition to the `Foo` class, a class
+`Foo_test` which will contain a `static Extension` for each extension field in
+the file along with a method for registering all the extensions in an
 `ExtensionRegistry` :
 
 -   `static final Extension bar`
@@ -479,7 +479,7 @@ service Foo {
 }
 ```
 
-The protocol buffer compiler can be invoked with the \`grpc\` option (e.g.
+The Protobuf compiler can be invoked with the \`grpc\` option (e.g.
 `--dart_out=grpc:output_folder`), in which case it will generate code to support
 [gRPC](//www.grpc.io/). See the
 [gRPC Dart Quickstart guide](https://grpc.io/docs/quickstart/dart.html)
diff --git a/content/reference/go/_index.md b/content/reference/go/_index.md
index f368a5f1f..3fce04156 100644
--- a/content/reference/go/_index.md
+++ b/content/reference/go/_index.md
@@ -2,6 +2,6 @@
 title = "Go Reference"
 weight = 600
 linkTitle = "Go"
-description = "Reference documentation for working with protocol buffer classes in Go"
+description = "Reference documentation for working with Protobuf classes in Go"
 type = "docs"
 +++
diff --git a/content/reference/go/faq.md b/content/reference/go/faq.md
index 922d3ae7f..43f2ef9f0 100644
--- a/content/reference/go/faq.md
+++ b/content/reference/go/faq.md
@@ -2,7 +2,7 @@
 title = "Go FAQ"
 weight = 620
 linkTitle = "FAQ"
-description = "A list of frequently asked questions about implementing protocol buffers in Go, with answer for each."
+description = "A list of frequently asked questions about implementing Protobuf in Go, with an answer for each."
 type = "docs"
 +++
 
@@ -12,7 +12,7 @@ type = "docs"
 
 The
 [`github.com/golang/protobuf`](https://pkg.go.dev/github.com/golang/protobuf?tab=overview)
-module is the original Go protocol buffer API.
+module is the original Go Protobuf API.
 
 The
 [`google.golang.org/protobuf`](https://pkg.go.dev/google.golang.org/protobuf?tab=overview)
@@ -33,12 +33,12 @@ may be used interchangeably.
 
 ### What are `proto1`, `proto2`, `proto3`, and editions? {#proto-versions}
 
-These are revisions of the protocol buffer *language*. It is different from the
-Go *implementation* of protobufs.
+These are revisions of the Protobuf *language*. They are different from the Go
+*implementation* of Protobuf.
 
-*   **Editions** are the newest and recommended way of writing Protocol Buffers.
+*   **Editions** are the newest and recommended way of writing Protobuf schemas.
     New features will be released as part of new editions. For more information,
-    see [Protocol Buffer Editions](/editions).
+    see [Protobuf Editions](/editions).
 
 *   `proto3` is a legacy version of the language. We encourage new code to use
     editions.
@@ -53,7 +53,7 @@ Go *implementation* of protobufs.
 
 *   [`"google.golang.org/protobuf/proto".Message`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Message)
     is an interface type implemented by all messages generated by the current
-    version of the protocol buffer compiler. Functions that operate on arbitrary
+    version of the Protobuf compiler. Functions that operate on arbitrary
     messages, such as
     [`proto.Marshal`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Marshal)
     or
@@ -71,10 +71,10 @@ Go *implementation* of protobufs.
     are interchangeable.
 
 *   [`"github.com/golang/protobuf/proto".Message`](https://pkg.go.dev/github.com/golang/protobuf/proto?tab=doc#Message)
-    is an interface type defined by the legacy Go protocol buffer API. All
-    generated message types implement this interface, but the interface does not
-    describe the behavior expected from these messages. New code should avoid
-    using this type.
+    is an interface type defined by the legacy Go Protobuf API. All generated
+    message types implement this interface, but the interface does not describe
+    the behavior expected from these messages. New code should avoid using this
+    type.
 
 ## Common problems
 
@@ -110,25 +110,25 @@ Update to a newer version with:
 go get -u github.com/golang/protobuf/proto
 ```
 
-### What is a protocol buffer namespace conflict? {#namespace-conflict}
+### What is a Protobuf namespace conflict? {#namespace-conflict}
 
-All protocol buffers declarations linked into a Go binary are inserted into a
-global registry.
+All Protobuf declarations linked into a Go binary are inserted into a global
+registry.
 
-Every protobuf declaration (for example, enums, enum values, or messages) has an
+Every Protobuf declaration (for example, enums, enum values, or messages) has an
 absolute name, which is the concatenation of the
 [package name](/programming-guides/proto2#packages) with
 the relative name of the declaration in the `.proto` source file (for example,
-`my.proto.package.MyMessage.NestedMessage`). The protobuf language assumes that
+`my.proto.package.MyMessage.NestedMessage`). The Protobuf language assumes that
 all declarations are universally unique.
 
-If two protobuf declarations linked into a Go binary have the same name, then
+If two Protobuf declarations linked into a Go binary have the same name, then
 this leads to a namespace conflict, and it is impossible for the registry to
 properly resolve that declaration by name. Depending on which version of Go
-protobufs is being used, this will either panic at init-time or silently drop
-the conflict and lead to a potential bug later during runtime.
+Protobuf is being used, this will either panic at init-time or silently drop the
+conflict and lead to a potential bug later during runtime.
 
-### How do I fix a protocol buffer namespace conflict? {#fix-namespace-conflict}
+### How do I fix a Protobuf namespace conflict? {#fix-namespace-conflict}
 
 The way to best fix a namespace conflict depends on the reason why a conflict is
 occurring.
@@ -137,7 +137,7 @@ Common ways that namespace conflicts occur:
 
 *   **Vendored .proto files.** When a single `.proto` file is generated into two
     or more Go packages and linked into the same Go binary, it conflicts on
-    every protobuf declaration in the generated Go packages. This typically
+    every Protobuf declaration in the generated Go packages. This typically
     occurs when a `.proto` file is vendored and a Go package is generated from
     it, or the generated Go package itself is vendored. Users should avoid
     vendoring and instead depend on a centralized Go package for that `.proto`
@@ -164,7 +164,7 @@ definitions.{{% /alert %}}
 
 Starting with v1.26.0 of the `google.golang.org/protobuf` module, a hard error
 will be reported when a Go program starts up that has multiple conflicting
-protobuf names linked into it. While it is preferable that the source of the
+Protobuf names linked into it. While it is preferable that the source of the
 conflict be fixed, the fatal error can be immediately worked around in one of
 two ways:
 
@@ -177,9 +177,9 @@ two ways:
     a particular Go binary can be set with an environment variable:
     `GOLANG_PROTOBUF_REGISTRATION_CONFLICT=warn ./main`
 
-### How do I use protocol buffer editions? {#using-editions}
+### How do I use Protobuf editions? {#using-editions}
 
-To use a protobuf edition, you must specify the edition in your `.proto` file.
+To use a Protobuf edition, you must specify the edition in your `.proto` file.
 For example, to use the 2023 edition, add the following to the top of your
 `.proto` file:
 
@@ -187,10 +187,10 @@ For example, to use the 2023 edition, add the following to the top of your
 edition = "2023";
 ```
 
-The protocol buffer compiler will then generate Go code that is compatible with
-the specified edition. With editions, you can also enable or disable specific
+The Protobuf compiler will then generate Go code that is compatible with the
+specified edition. With editions, you can also enable or disable specific
 features for your `.proto` file. For more information, see
-[Protocol Buffer Editions](/editions/overview).
+[Protobuf Editions](/editions/overview).
 
 ### How do I control the behavior of my generated Go code? {#controlling-generated-code}
 
@@ -205,23 +205,23 @@ edition = "2023";
 option features.(pb.go).api_level = API_OPAQUE;
 ```
 
-When `api_level` is set to `API_OPAQUE`, the Go code generated by the protocol
-buffer compiler hides struct fields so they can no longer be directly accessed.
+When `api_level` is set to `API_OPAQUE`, the Go code generated by the Protobuf
+compiler hides struct fields so they can no longer be directly accessed.
 Instead, new accessor methods are created for getting, setting, or clearing a
 field.
 
 For a complete list of available features and their descriptions, see
 [Features for Editions](/editions/features).
 
-### Why does `reflect.DeepEqual` behave unexpectedly with protobuf messages? {#deepequal}
+### Why does `reflect.DeepEqual` behave unexpectedly with Protobuf messages? {#deepequal}
 
-Generated protocol buffer message types include internal state which can vary
-even between equivalent messages.
+Generated Protobuf message types include internal state which can vary even
+between equivalent messages.
 
 In addition, the `reflect.DeepEqual` function is not aware of the semantics of
-protocol buffer messages, and can report differences where none exist. For
-example, a map field containing a `nil` map and one containing a zero-length,
-non-`nil` map are semantically equivalent, but will be reported as unequal by
+Protobuf messages, and can report differences where none exist. For example, a
+map field containing a `nil` map and one containing a zero-length, non-`nil` map
+are semantically equivalent, but will be reported as unequal by
 `reflect.DeepEqual`.
 
 Use the
@@ -252,12 +252,12 @@ if diff := cmp.Diff(a, b, protocmp.Transform()); diff != "" {
 > promise in the contract: all observable behaviors of your system will be
 > depended on by somebody.
 
-A design goal of the latest version of the Go protocol buffer API is to avoid,
-where possible, providing observable behaviors that we cannot promise to keep
-stable in the future. It is our philosophy that deliberate instability in areas
-where we make no promises is better than giving the illusion of stability, only
-for that to change in the future after a project has potentially been long
-depending on that false assumption.
+A design goal of the latest version of the Go Protobuf API is to avoid, where
+possible, providing observable behaviors that we cannot promise to keep stable
+in the future. It is our philosophy that deliberate instability in areas where
+we make no promises is better than giving the illusion of stability, only for
+that to change in the future after a project has potentially been long depending
+on that false assumption.
 
 ### Why does the text of errors keep changing? {#unstable-errors}
 
@@ -274,7 +274,7 @@ according to [`errors.Is`](https://pkg.go.dev/errors?tab=doc#Is).
 ### Why does the output of [`protojson`](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson) keep changing? {#unstable-json}
 
 We make no promises about the long-term stability of Go's implementation of the
-[JSON format for protocol buffers](/programming-guides/proto3#json).
+[JSON format for Protobuf](/programming-guides/proto3#json).
 The specification only specifies what is valid JSON, but provides no
 specification for a *canonical* format for how a marshaler ought to *exactly*
 format a given message. To avoid giving the illusion that the output is stable,
@@ -287,7 +287,7 @@ a JSON formatter.
 ### Why does the output of [`prototext`](https://pkg.go.dev/google.golang.org/protobuf/encoding/prototext) keep changing? {#unstable-text}
 
 We make no promises about the long-term stability of Go's implementation of the
-text format. There is no canonical specification of the protobuf text format,
+text format. There is no canonical specification of the Protobuf text format,
 and we would like to preserve the ability to make improvements in the
 `prototext` package output in the future. Since we don't promise stability in
 the package's output, we've deliberately introduced instability to discourage
@@ -301,25 +301,25 @@ can be directly invoked in Go using
 
 ## Miscellaneous
 
-### How do I use a protocol buffer message as a hash key? {#hash}
+### How do I use a Protobuf message as a hash key? {#hash}
 
-You need canonical serialization, where the marshaled output of a protocol
-buffer message is guaranteed to be stable over time. Unfortunately, no
-specification for canonical serialization exists at this time. You'll need to
-write your own or find a way to avoid needing one.
+You need canonical serialization, where the marshaled output of a Protobuf
+message is guaranteed to be stable over time. Unfortunately, no specification
+for canonical serialization exists at this time. You'll need to write your own
+or find a way to avoid needing one.
 
-### Can I add a new feature to the Go protocol buffer implementation? {#new-feature}
+### Can I add a new feature to the Go Protobuf implementation? {#new-feature}
 
 Maybe. We always like suggestions, but we're very cautious about adding new
 things.
 
-The Go implementation of protocol buffers strives to be consistent with the
-other language implementations. As such, we tend to shy away from feature that
-are overly specialized to just Go. Go-specific features hinder the goal of
-protocol buffers being a language-neutral data interchange format.
+The Go implementation of Protobuf strives to be consistent with the other
+language implementations. As such, we tend to shy away from features that are
+overly specialized to just Go. Go-specific features hinder the goal of Protobuf
+being a language-neutral data interchange format.
 
 Unless your idea is specific to the Go implementation, you should join the
-[protobuf discussion group](http://groups.google.com/group/protobuf) and suggest
+[Protobuf discussion group](http://groups.google.com/group/protobuf) and suggest
 it there.
 
 If you have an idea for the Go implementation, file an issue on our issue
@@ -329,7 +329,7 @@ tracker:
 ### Can I add an option to `Marshal` or `Unmarshal` to customize it? {#new-marshal-option}
 
 Only if that option exists in other implementations (e.g., C++, Java). The
-encoding of protocol buffers (binary, JSON, and text) must be consistent across
+encoding of Protobuf messages (binary, JSON, and text) must be consistent across
 implementations, so a program written in one language is able to read messages
 written by another one.
 
@@ -339,6 +339,5 @@ option exist in at least one other supported implementation.
 
 ### Can I customize the code generated by `protoc-gen-go`? {#custom-code}
 
-In general, no. Protocol buffers are intended to be a language-agnostic data
-interchange format, and implementation-specific customizations run counter to
-that intent.
+In general, no. Protobuf is intended to be a language-agnostic data interchange
+format, and implementation-specific customizations run counter to that intent.
diff --git a/content/reference/go/go-generated-opaque.md b/content/reference/go/go-generated-opaque.md
index f1451f213..ec79955e4 100644
--- a/content/reference/go/go-generated-opaque.md
+++ b/content/reference/go/go-generated-opaque.md
@@ -2,14 +2,14 @@
 title = "Go Generated Code Guide (Opaque)"
 weight = 615
 linkTitle = "Generated Code Guide (Opaque)"
-description = "Describes exactly what Go code the protocol buffer compiler generates for any given protocol definition."
+description = "Describes exactly what Go code the Protobuf compiler generates for any given protocol definition."
 type = "docs"
 +++
 
-Any differences between
-proto2 and proto3 generated code are highlighted - note that these differences
-are in the generated code as described in this document, not the base API, which
-are the same in both versions. You should read the
+Any differences between proto2
+and proto3 generated code are highlighted - note that these differences are in
+the generated code as described in this document, not the base API, which are
+the same in both versions. You should read the
 [proto2 language guide](/programming-guides/proto2)
 and/or the
 [proto3 language guide](/programming-guides/proto3)
@@ -26,7 +26,7 @@ introduction of the Opaque API. {{% /alert %}}
 
 ## Compiler Invocation {#invocation}
 
-The protocol buffer compiler requires a plugin to generate Go code. Install it
+The Protobuf compiler requires a plugin to generate Go code. Install it
 using Go 1.16 or higher by running:
 
 ```shell
@@ -35,9 +35,9 @@ go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
 
 This will install a `protoc-gen-go` binary in `$GOBIN`. Set the `$GOBIN`
 environment variable to change the installation location. It must be in your
-`$PATH` for the protocol buffer compiler to find it.
+`$PATH` for the Protobuf compiler to find it.
 
-The protocol buffer compiler produces Go output when invoked with the `go_out`
+The Protobuf compiler produces Go output when invoked with the `go_out`
 flag. The argument to the `go_out` flag is the directory where you want the
 compiler to write your Go output. The compiler creates a single source file for
 each `.proto` file input. The name of the output file is created by replacing
@@ -133,7 +133,7 @@ See the \"Compiler Invocation\" section above for details.
 
 There is no correlation between the Go import path and the
 [`package` specifier](/programming-guides/proto3#packages)
-in the `.proto` file. The latter is only relevant to the protobuf namespace,
+in the `.proto` file. The latter is only relevant to the Protobuf namespace,
 while the former is only relevant to the Go namespace. Also, there is no
 correlation between the Go import path and the `.proto` import path.
 
@@ -193,7 +193,7 @@ Given a simple message declaration:
 message Artist {}
 ```
 
-the protocol buffer compiler generates a struct called `Artist`. An `*Artist`
+the Protobuf compiler generates a struct called `Artist`. An `*Artist`
 implements the
 [`proto.Message`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Message)
 interface.
@@ -240,8 +240,8 @@ In this case, the compiler generates two structs: `Artist` and `Artist_Name`.
 
 ## Fields
 
-The protocol buffer compiler generates accessor methods (setters and getters)
-for each field defined within a message.
+The Protobuf compiler generates accessor methods (setters and getters) for each
+field defined within a message.
 
 Note that the generated Go accessor methods always use camel-case naming, even
 if the field name in the `.proto` file uses lower-case with underscores
@@ -428,7 +428,7 @@ func (m *MerchBooth) SetItems(v map[string]*MerchItem) { ... }
 
 ### Oneof Fields {#oneof}
 
-For a oneof field, the protobuf compiler generates accessors for each of the
+For a oneof field, the Protobuf compiler generates accessors for each of the
 [singular fields](#singular-scalar-proto2) within the oneof.
 
 For this message with a oneof field:
@@ -507,7 +507,7 @@ default:
 Builders are a convenient way to construct and initialize a message within a
 single expression, especially when working with nested messages like unit tests.
 
-Contrary to builders in other languages (like Java), Go protobuf builders are
+Contrary to builders in other languages (like Java), Go Protobuf builders are
 not meant to be passed around between functions. Instead, call `Build()`
 immediately and pass the resulting proto message instead, using setters to
 modify fields.
@@ -543,8 +543,7 @@ message Venue {
 }
 ```
 
-the protocol buffer compiler generates a type and a series of constants with
-that type:
+the Protobuf compiler generates a type and a series of constants with that type:
 
 ```go
 type Venue_Kind int32
@@ -592,9 +591,8 @@ returns the corresponding pointer:
 func (Genre) Enum() *Genre
 ```
 
-The protocol buffer compiler generates a constant for each value in the enum.
-For enums within a message, the constants begin with the enclosing message's
-name:
+The Protobuf compiler generates a constant for each value in the enum. For enums
+within a message, the constants begin with the enclosing message's name:
 
 ```go
 const (
@@ -617,7 +615,7 @@ const (
 )
 ```
 
-The protobuf compiler also generates a map from integer values to the string
+The Protobuf compiler also generates a map from integer values to the string
 names and a map from the names to the values:
 
 ```go
@@ -651,7 +649,7 @@ extend Concert {
 }
 ```
 
-The protocol buffer compiler will generate a
+The Protobuf compiler will generate a
 [`protoreflect.ExtensionType`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#ExtensionType)
 value named `E_Promo_id`. This value may be used with the
 [`proto.GetExtension`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#GetExtension),
diff --git a/content/reference/go/go-generated.md b/content/reference/go/go-generated.md
index b571e3a07..0ecceab13 100644
--- a/content/reference/go/go-generated.md
+++ b/content/reference/go/go-generated.md
@@ -2,12 +2,12 @@
 title = "Go Generated Code Guide (Open)"
 weight = 610
 linkTitle = "Generated Code Guide (Open)"
-description = "Describes exactly what Go code the protocol buffer compiler generates for any given protocol definition."
+description = "Describes exactly what Go code the Protobuf compiler generates for any given protocol definition."
 type = "docs"
 +++
 
-Any differences between
-proto2, proto3, and editions generated code are highlighted - note that these
+Any differences between proto2,
+proto3, and editions generated code are highlighted - note that these
 differences are in the generated code as described in this document, not the
 base API, which are the same in both versions. You should read the
 [proto2 language guide](/programming-guides/proto2),
@@ -25,7 +25,7 @@ introduction of the Opaque API. {{% /alert %}}
 
 ## Compiler Invocation {#invocation}
 
-The protocol buffer compiler requires a plugin to generate Go code. Install it
+The Protobuf compiler requires a plugin to generate Go code. Install it
 using Go 1.16 or higher by running:
 
 ```shell
@@ -34,9 +34,9 @@ go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
 
 This will install a `protoc-gen-go` binary in `$GOBIN`. Set the `$GOBIN`
 environment variable to change the installation location. It must be in your
-`$PATH` for the protocol buffer compiler to find it.
+`$PATH` for the Protobuf compiler to find it.
 
-The protocol buffer compiler produces Go output when invoked with the `go_out`
+The Protobuf compiler produces Go output when invoked with the `go_out`
 flag. The argument to the `go_out` flag is the directory where you want the
 compiler to write your Go output. The compiler creates a single source file for
 each `.proto` file input. The name of the output file is created by replacing
@@ -132,7 +132,7 @@ See the \"Compiler Invocation\" section above for details.
 
 There is no correlation between the Go import path and the
 [`package` specifier](/programming-guides/proto3#packages)
-in the `.proto` file. The latter is only relevant to the protobuf namespace,
+in the `.proto` file. The latter is only relevant to the Protobuf namespace,
 while the former is only relevant to the Go namespace. Also, there is no
 correlation between the Go import path and the `.proto` import path.
 
@@ -192,7 +192,7 @@ Given a simple message declaration:
 message Artist {}
 ```
 
-the protocol buffer compiler generates a struct called `Artist`. An `*Artist`
+the Protobuf compiler generates a struct called `Artist`. An `*Artist`
 implements the
 [`proto.Message`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Message)
 interface.
@@ -239,9 +239,9 @@ In this case, the compiler generates two structs: `Artist` and `Artist_Name`.
 
 ## Fields
 
-The protocol buffer compiler generates a struct field for each field defined
-within a message. The exact nature of this field depends on its type and whether
-it is a singular, repeated, map, or oneof field.
+The Protobuf compiler generates a struct field for each field defined within a
+message. The exact nature of this field depends on its type and whether it is a
+singular, repeated, map, or oneof field.
 
 Note that the generated Go field names always use camel-case naming, even if the
 field name in the `.proto` file uses lower-case with underscores
@@ -423,7 +423,7 @@ type MerchBooth struct {
 
 ### Oneof Fields {#oneof}
 
-For a oneof field, the protobuf compiler generates a single field with an
+For a oneof field, the Protobuf compiler generates a single field with an
 interface type `isMessageName_MyField`. It also generates a struct for each of
 the [singular fields](#singular-scalar-proto2) within the oneof. These all
 implement this `isMessageName_MyField` interface.
@@ -515,8 +515,7 @@ message Venue {
 }
 ```
 
-the protocol buffer compiler generates a type and a series of constants with
-that type:
+the Protobuf compiler generates a type and a series of constants with that type:
 
 ```go
 type Venue_Kind int32
@@ -564,9 +563,8 @@ returns the corresponding pointer:
 func (Genre) Enum() *Genre
 ```
 
-The protocol buffer compiler generates a constant for each value in the enum.
-For enums within a message, the constants begin with the enclosing message's
-name:
+The Protobuf compiler generates a constant for each value in the enum. For enums
+within a message, the constants begin with the enclosing message's name:
 
 ```go
 const (
@@ -589,7 +587,7 @@ const (
 )
 ```
 
-The protobuf compiler also generates a map from integer values to the string
+The Protobuf compiler also generates a map from integer values to the string
 names and a map from the names to the values:
 
 ```go
@@ -623,7 +621,7 @@ extend Concert {
 }
 ```
 
-The protocol buffer compiler will generate a
+The Protobuf compiler will generate a
 [`protoreflect.ExtensionType`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#ExtensionType)
 value named `E_Promo_id`. This value may be used with the
 [`proto.GetExtension`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#GetExtension),
diff --git a/content/reference/go/opaque-faq.md b/content/reference/go/opaque-faq.md
index 64426f98f..1cc387791 100644
--- a/content/reference/go/opaque-faq.md
+++ b/content/reference/go/opaque-faq.md
@@ -19,10 +19,10 @@ type = "docs"
 }
 
 
-The Opaque API is the latest version of the Protocol Buffers implementation for
-the Go programming language. The old version is now called Open Struct API. See
-the [Go Protobuf: The new Opaque API](https://go.dev/blog/protobuf-opaque) blog
-post for an introduction.
+The Opaque API is the latest version of the Protobuf implementation for the Go
+programming language. The old version is now called Open Struct API. See the
+[Go Protobuf: The new Opaque API](https://go.dev/blog/protobuf-opaque) blog post
+for an introduction.
 
 This FAQ answers common questions about the new API and the migration process.
 
@@ -216,8 +216,8 @@ later need to be freed by the garbage collector.
 
 ## Should I Use Builders or Setters? {#builders-vs-setters}
 
-When constructing an empty protocol buffer, you should use `new` or an empty
-composite literals. Both are equivalently idiomatic to construct a zero
+When constructing an empty Protobuf message, you should use `new` or an empty
+composite literal. Both are equivalently idiomatic to construct a zero
 initialized value in Go and are more performant than an empty builder.
 
 ```go {.good}
@@ -230,7 +230,7 @@ m2 := &pb.M{}
 m1 := pb.M_builder{}.Build()
 ```
 
-In cases where you need to construct non-empty protocol buffers, you have the
+In cases where you need to construct non-empty Protobuf messages, you have the
 choice between using setters or using builders. Either is fine, but most people
 will find builders more readable. If the code you are writing needs to perform
 well,
@@ -326,7 +326,7 @@ The
 explains:
 
 > This performance improvement [modeling field presence more efficiently]
-> depends heavily on your protobuf message shape: The change only affects
+> depends heavily on your Protobuf message shape: The change only affects
 > elementary fields like integers, booleans, enums and floats, but not strings,
 > repeated fields or submessages.
 
diff --git a/content/reference/go/opaque-migration-manual.md b/content/reference/go/opaque-migration-manual.md
index e32b8fe19..b26a9e8bc 100644
--- a/content/reference/go/opaque-migration-manual.md
+++ b/content/reference/go/opaque-migration-manual.md
@@ -6,9 +6,9 @@ description = "Describes a manual migration to the Opaque API."
 type = "docs"
 +++
 
-The Opaque API is the latest version of the Protocol Buffers implementation for
-the Go programming language. The old version is now called Open Struct API. See
-the [Go Protobuf: Releasing the Opaque API](https://go.dev/blog/protobuf-opaque)
+The Opaque API is the latest version of the Protobuf implementation for the Go
+programming language. The old version is now called Open Struct API. See the
+[Go Protobuf: Releasing the Opaque API](https://go.dev/blog/protobuf-opaque)
 blog post for an introduction.
 
 This is a user guide for migrating Go Protobuf usages from the older Open Struct
@@ -26,7 +26,7 @@ provides more detail. This guide compares the old and new API side-by-side.
 
 ### Message Construction
 
-Suppose there is a protobuf message defined like this:
+Suppose there is a Protobuf message defined like this:
 
 ```proto
 message Foo {
@@ -665,5 +665,5 @@ Some common libraries do use Go `reflect` under the hood, examples are:
         [protobuf/encoding/protojson](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson).
 *   [pretty](https://pkg.go.dev/github.com/kr/pretty)
 *   [cmp](https://pkg.go.dev/github.com/google/go-cmp/cmp)
-    *   To use `cmp.Equal` properly with protobuf messages, use
+    *   To use `cmp.Equal` properly with Protobuf messages, use
         [protocmp.Transform](https://pkg.go.dev/google.golang.org/protobuf/testing/protocmp#Transform)
diff --git a/content/reference/go/opaque-migration.md b/content/reference/go/opaque-migration.md
index f96eb396e..33601171b 100644
--- a/content/reference/go/opaque-migration.md
+++ b/content/reference/go/opaque-migration.md
@@ -6,9 +6,9 @@ description = "Describes the automated migration to the Opaque API."
 type = "docs"
 +++
 
-The Opaque API is the latest version of the Protocol Buffers implementation for
-the Go programming language. The old version is now called Open Struct API. See
-the [Go Protobuf: Releasing the Opaque API](https://go.dev/blog/protobuf-opaque)
+The Opaque API is the latest version of the Protobuf implementation for the Go
+programming language. The old version is now called Open Struct API. See the
+[Go Protobuf: Releasing the Opaque API](https://go.dev/blog/protobuf-opaque)
 blog post for an introduction.
 
 The migration to the Opaque API happens incrementally, on a per-proto-message or
@@ -77,20 +77,20 @@ guide. {{% /alert %}}
 ### Project Preparation {#projectprep}
 
 Ensure your build environment and project are using recent-enough versions of
-Protocol Buffers and Go Protobuf:
+Protobuf and Go Protobuf:
 
-1.  Update the protobuf compiler (protoc) from
-    [the protobuf release page](https://github.com/protocolbuffers/protobuf/releases/latest)
+1.  Update the Protobuf compiler (protoc) from
+    [the Protobuf release page](https://github.com/protocolbuffers/protobuf/releases/latest)
     to version 29.0 or newer.
 
-1.  Update the protobuf compiler Go plugin (protoc-gen-go) to version 1.36.0 or
+1.  Update the Protobuf compiler Go plugin (protoc-gen-go) to version 1.36.0 or
     newer:
 
     ```
     go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
     ```
 
-1.  In each project, update the `go.mod` file to use the protobuf module in
+1.  In each project, update the `go.mod` file to use the Protobuf module in
     version 1.36.0 or newer:
 
     ```
@@ -114,7 +114,7 @@ open2opaque setapi -api HYBRID $(find . -name "*.proto")
 
 Then,
 [re-compile](/getting-started/gotutorial#compiling-protocol-buffers)
-your protocol buffers.
+your `.proto` files.
 
 Your existing code will continue to build. The Hybrid API is a step between the
 Open and Opaque API which adds the new accessor methods but keeps struct fields
@@ -152,7 +152,7 @@ if req.HasIPAddress() {
 logEntry.SetBackendServer(host)
 ```
 
-Another common example is to initialize a protobuf message with a struct
+Another common example is to initialize a Protobuf message with a struct
 literal:
 
 ```go
diff --git a/content/reference/java/_index.md b/content/reference/java/_index.md
index 8636a1c9c..2e6412a39 100644
--- a/content/reference/java/_index.md
+++ b/content/reference/java/_index.md
@@ -2,6 +2,6 @@
 title = "Java Reference"
 weight = 640
 linkTitle = "Java"
-description = "Reference documentation for working with protocol buffer classes in Java."
+description = "Reference documentation for working with Protobuf classes in Java."
 type = "docs"
 +++
diff --git a/content/reference/java/java-generated.md b/content/reference/java/java-generated.md
index a5d6185e9..09932c594 100644
--- a/content/reference/java/java-generated.md
+++ b/content/reference/java/java-generated.md
@@ -2,31 +2,31 @@
 title = "Java Generated Code Guide"
 weight = 650
 linkTitle = "Generated Code Guide"
-description = "Describes exactly what Java code the protocol buffer compiler generates for any given protocol definition."
+description = "Describes exactly what Java code the Protobuf compiler generates for any given protocol definition."
 type = "docs"
 +++
 
-Any
-differences between proto2, proto3, and Editions generated code are
-highlighted—note that these differences are in the generated code as
-described in this document, not the base message classes/interfaces, which are
-the same in all versions. You should read the
+Any differences between
+proto2, proto3, and Editions generated code are highlighted—note that
+these differences are in the generated code as described in this document, not
+the base message classes/interfaces, which are the same in all versions. You
+should read the
 [proto2 language guide](/programming-guides/proto2),
 [proto3 language guide](/programming-guides/proto3),
 and/or
 [Editions language guide](/programming-guides/editions)
 before reading this document.
 
-Note that no Java protocol buffer methods accept or return nulls unless
-otherwise specified.
+Note that no Java Protobuf methods accept or return nulls unless otherwise
+specified.
 
 ## Compiler Invocation {#invocation}
 
-The protocol buffer compiler produces Java output when invoked with the
-`--java_out=` command-line flag. The parameter to the `--java_out=` option is
-the directory where you want the compiler to write your Java output. For each
-`.proto` file input, the compiler creates a wrapper `.java` file containing a
-Java class that represents the `.proto` file itself.
+The Protobuf compiler produces Java output when invoked with the `--java_out=`
+command-line flag. The parameter to the `--java_out=` option is the directory
+where you want the compiler to write your Java output. For each `.proto` file
+input, the compiler creates a wrapper `.java` file containing a Java class that
+represents the `.proto` file itself.
 
 If the `.proto` file contains a line like the following:
 
@@ -65,7 +65,7 @@ enum, or message (including nested types) in the file with the same name,
     wrapper class will generate a class name of `FooServiceOuterClass`.
 
 {{% alert title="Note" color="note" %}}If you are
-using the deprecated v1 of the protobuf API, `OuterClass` is added regardless of
+using the deprecated v1 of the Protobuf API, `OuterClass` is added regardless of
 any collisions with message names.
 {{% /alert %}}
 
@@ -99,20 +99,20 @@ protoc --proto_path=src --java_out=build/gen src/foo.proto
 ```
 
 If `foo.proto`'s Java package is `com.example` and it doesn't enable
-`java_multiple_files` and its outer classname is `FooProtos`, then the protocol
-buffer compiler will generate the file `build/gen/com/example/FooProtos.java`.
-The protocol buffer compiler will automatically create the `build/gen/com` and
+`java_multiple_files` and its outer classname is `FooProtos`, then the Protobuf
+compiler will generate the file `build/gen/com/example/FooProtos.java`. The
+Protobuf compiler will automatically create the `build/gen/com` and
 `build/gen/com/example` directories if needed. However, it will not create
 `build/gen` or `build`; they must already exist. You can specify multiple
 `.proto` files in a single invocation; all output files will be generated at
 once.
 
-When outputting Java code, the protocol buffer compiler's ability to output
-directly to JAR archives is particularly convenient, as many Java tools are able
-to read source code directly from JAR files. To output to a JAR file, simply
-provide an output location ending in `.jar`. Note that only the Java source code
-is placed in the archive; you must still compile it separately to produce Java
-class files.
+When outputting Java code, the Protobuf compiler's ability to output directly to
+JAR archives is particularly convenient, as many Java tools are able to read
+source code directly from JAR files. To output to a JAR file, simply provide an
+output location ending in `.jar`. Note that only the Java source code is placed
+in the archive; you must still compile it separately to produce Java class
+files.
 
 ## Packages {#package}
 
@@ -141,7 +141,7 @@ are not expected to start with a backwards domain name.
 
 ## Messages {#message}
 
-If you are designing a new protocol buffer schema, see
+If you are designing a new Protobuf schema, see
 [the recommendations for Java proto names](/reference/java/java-proto-names).
 
 Given a simple message declaration:
@@ -150,9 +150,9 @@ Given a simple message declaration:
 message Foo {}
 ```
 
-The protocol buffer compiler generates a class called `Foo`, which implements
-the `Message` interface. The class is declared `final`; no further subclassing
-is allowed. `Foo` extends `GeneratedMessage`, but this should be considered an
+The Protobuf compiler generates a class called `Foo`, which implements the
+`Message` interface. The class is declared `final`; no further subclassing is
+allowed. `Foo` extends `GeneratedMessage`, but this should be considered an
 implementation detail. By default, `Foo` overrides many methods of
 `GeneratedMessage` with specialized versions for maximum speed. However, if the
 `.proto` file contains the line:
@@ -211,14 +211,14 @@ the following static methods:
 Message objects—such as instances of the `Foo` class described
 above—are immutable, just like a Java `String`. To construct a message
 object, you need to use a *builder*. Each message class has its own builder
-class—so in our `Foo` example, the protocol buffer compiler generates a
-nested class `Foo.Builder` which can be used to build a `Foo`. `Foo.Builder`
-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. You can get a `Foo.Builder`
-by calling the static method `Foo.newBuilder()`.
+class—so in our `Foo` example, the Protobuf compiler generates a nested
+class `Foo.Builder` which can be used to build a `Foo`. `Foo.Builder` 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. 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
@@ -290,11 +290,11 @@ inside `Foo`.
 
 ## Fields {#fields}
 
-In addition to the methods described in the previous section, the protocol
-buffer compiler generates a set of accessor methods for each field defined
-within the message in the `.proto` file. The methods that read the field value
-are defined both in the message class and its corresponding builder; the methods
-that modify the value are defined in the builder only.
+In addition to the methods described in the previous section, the Protobuf
+compiler generates a set of accessor methods for each field defined within the
+message in the `.proto` file. The methods that read the field value are defined
+both in the message class and its corresponding builder; the methods that modify
+the value are defined in the builder only.
 
 Note that method names always use camel-case naming, even if the field name in
 the `.proto` file uses lower-case with underscores
@@ -519,7 +519,7 @@ builder:
 #### Name Conflicts {#conflicts}
 
 If another non-repeated field has a name that conflicts with one of the repeated
-field's generated methods, then both field names will have their protobuf field
+field's generated methods, then both field names will have their Protobuf field
 number appended to the end.
 
 For these field definitions:
@@ -553,8 +553,8 @@ oneof choice {
 ```
 
 All the fields in the `choice` oneof will use a single private field for their
-value. In addition, the protocol buffer compiler will generate a Java enum type
-for the oneof case, as follows:
+value. In addition, the Protobuf compiler will generate a Java enum type for the
+oneof case, as follows:
 
 ```java
 public enum ChoiceCase
@@ -682,7 +682,7 @@ class Any {
   // message.
   public boolean isSameTypeAs(Message message);
 
-  // Unpacks Any into a message with the same type as the given messsage.
+  // Unpacks Any into a message with the same type as the given message.
   // Throws exception if the type doesn’t match or parsing the payload fails.
   public  T unpackSameTypeAs(T message)
       throws InvalidProtocolBufferException;
@@ -706,8 +706,8 @@ enum Foo {
 }
 ```
 
-The protocol buffer compiler will generate a Java enum type called `Foo` with
-the same set of values. If you are using proto3, it also adds the special value
+The Protobuf compiler will generate a Java enum type called `Foo` with the same
+set of values. If you are using proto3, it also adds the special value
 `UNRECOGNIZED` to the enum type. In Editions, `OPEN` enums also have a
 `UNRECOGNIZED` value, while `CLOSED` enums do not. The values of the generated
 enum type have the following special methods:
@@ -763,11 +763,11 @@ symbols with the same number are just aliases.
 An enum can be defined nested within a message type. The compiler generates the
 Java enum definition nested within that message type's class.
 
-**Caution: when generating Java code, the maximum number of values in a protobuf
+**Caution: when generating Java code, the maximum number of values in a Protobuf
 enum may be surprisingly low**—in the worst case, the maximum is slightly
 over 1,700 values. This limit is due to per-method size limits for Java
 bytecode, and it varies across Java implementations, different versions of the
-protobuf suite, and any options set on the enum in the `.proto` file.
+Protobuf suite, and any options set on the enum in the `.proto` file.
 
 ## Extensions {#extension}
 
@@ -781,7 +781,7 @@ message Foo {
 }
 ```
 
-The protocol buffer compiler will make `Foo` extend
+The Protobuf compiler will make `Foo` extend
 `GeneratedMessage.ExtendableMessage` instead of the usual `GeneratedMessage`.
 Similarly, `Foo`'s builder will extend `GeneratedMessage.ExtendableBuilder`. You
 should never refer to these base types by name (`GeneratedMessage` is considered
@@ -809,9 +809,8 @@ extend Foo {
 }
 ```
 
-The protocol buffer compiler generates an "extension identifier" called `bar`,
-which you can use with `Foo`'s extension accessors to access this extension,
-like so:
+The Protobuf compiler generates an "extension identifier" called `bar`, which
+you can use with `Foo`'s extension accessors to access this extension, like so:
 
 ```java
 Foo foo =
@@ -887,11 +886,11 @@ If the `.proto` file contains the following line:
 option java_generic_services = true;
 ```
 
-Then the protocol buffer compiler will generate code based on the service
-definitions found in the file as described in this section. However, the
-generated code may be undesirable as it is not tied to any particular RPC
-system, and thus requires more levels of indirection than code tailored to one
-system. If you do NOT want this code to be generated, add this line to the file:
+Then the Protobuf compiler will generate code based on the service definitions
+found in the file as described in this section. However, the generated code may
+be undesirable as it is not tied to any particular RPC system, and thus requires
+more levels of indirection than code tailored to one system. If you do NOT want
+this code to be generated, add this line to the file:
 
 ```proto
 option java_generic_services = false;
@@ -908,8 +907,8 @@ to generate code appropriate for the system. These plugins are likely to require
 that abstract services are disabled, so that they can generate their own classes
 of the same names.
 
-The remainder of this section describes what the protocol buffer compiler
-generates when abstract services are enabled.
+The remainder of this section describes what the Protobuf compiler generates
+when abstract services are enabled.
 
 ### Interface {#interface}
 
@@ -921,8 +920,8 @@ service Foo {
 }
 ```
 
-The protocol buffer compiler will generate an abstract class `Foo` to represent
-this service. `Foo` will have an abstract method for each method defined in the
+The Protobuf compiler will generate an abstract class `Foo` to represent this
+service. `Foo` will have an abstract method for each method defined in the
 service definition. In this case, the method `Bar` is defined as:
 
 ```java
@@ -934,8 +933,8 @@ The parameters are equivalent to the parameters of `Service.CallMethod()`,
 except that the `method` argument is implied and `request` and `done` specify
 their exact type.
 
-`Foo` subclasses the `Service` interface. The protocol buffer compiler
-automatically generates implementations of the methods of `Service` as follows:
+`Foo` subclasses the `Service` interface. The Protobuf compiler automatically
+generates implementations of the methods of `Service` as follows:
 
 -   `getDescriptorForType`: Returns the service's `ServiceDescriptor`.
 -   `callMethod`: Determines which method is being called based on the provided
@@ -971,8 +970,8 @@ To recap, when implementing your own service, you have two options:
 
 ### Stub {#stub}
 
-The protocol buffer compiler also generates a "stub" implementation of every
-service interface, which is used by clients wishing to send requests to servers
+The Protobuf compiler also generates a "stub" implementation of every service
+interface, which is used by clients wishing to send requests to servers
 implementing the service. For the `Foo` service (above), the stub implementation
 `Foo.Stub` will be defined as a nested class.
 
@@ -987,7 +986,7 @@ The stub additionally implements each of the service's methods as a wrapper
 around the channel. Calling one of the methods simply calls
 `channel.callMethod()`.
 
-The Protocol Buffer library does not include an RPC implementation. However, it
+The Protobuf library does not include an RPC implementation. However, it
 includes all of the tools you need to hook up a generated service class to any
 arbitrary RPC implementation of your choice. You need only provide
 implementations of `RpcChannel` and `RpcController`.
@@ -998,7 +997,7 @@ The RPC classes described above all have non-blocking semantics: when you call a
 method, you provide a callback object which will be invoked once the method
 completes. Often it is easier (though possibly less scalable) to write code
 using blocking semantics, where the method simply doesn't return until it is
-done. To accommodate this, the protocol buffer compiler also generates blocking
+done. To accommodate this, the Protobuf compiler also generates blocking
 versions of your service class. `Foo.BlockingInterface` is equivalent to
 `Foo.Interface` except that each method simply returns the result rather than
 call a callback. So, for example, `bar` is defined as:
@@ -1046,11 +1045,11 @@ complicated. You should probably look at the `protoc` source code, particularly
 
 Do not generate code which relies on private class members declared by the
 standard code generator, as these implementation details may change in future
-versions of Protocol Buffers.
+versions of Protobuf.
 
 ## Utility Classes {#utility-classes}
 
-Protocol buffer provides
+Protobuf provides
 [utility classes](/reference/java/api-docs/com/google/protobuf/util/package-summary.html)
 for message comparison, JSON conversion and working with
-[well-known types (predefined protocol buffer messages for common use-cases).](/reference/protobuf/google.protobuf)
+[well-known types (predefined Protobuf messages for common use-cases)](/reference/protobuf/google.protobuf).
diff --git a/content/reference/kotlin/_index.md b/content/reference/kotlin/_index.md
index 82de16ff8..ddc995987 100644
--- a/content/reference/kotlin/_index.md
+++ b/content/reference/kotlin/_index.md
@@ -2,6 +2,6 @@
 title = "Kotlin Reference"
 weight = 670
 linkTitle = "Kotlin"
-description = "Reference documentation for working with protocol buffer classes in Kotlin."
+description = "Reference documentation for working with Protobuf classes in Kotlin."
 type = "docs"
 +++
diff --git a/content/reference/kotlin/api-docs/_index.md b/content/reference/kotlin/api-docs/_index.md
index a773cb705..90bb4c3f4 100644
--- a/content/reference/kotlin/api-docs/_index.md
+++ b/content/reference/kotlin/api-docs/_index.md
@@ -2,7 +2,7 @@
 title = "Kotlin Reference"
 weight = 670
 linkTitle = "Kotlin"
-description = "This section contains reference documentation for working with protocol buffers in Kotlin."
+description = "This section contains reference documentation for working with Protobuf in Kotlin."
 type = "docs"
 +++
 
diff --git a/content/reference/kotlin/api-docs/protobuf-kotlin/com.google.protobuf.kotlin/-dsl-list/_index.md b/content/reference/kotlin/api-docs/protobuf-kotlin/com.google.protobuf.kotlin/-dsl-list/_index.md
index b5245e02c..307de7c5d 100644
--- a/content/reference/kotlin/api-docs/protobuf-kotlin/com.google.protobuf.kotlin/-dsl-list/_index.md
+++ b/content/reference/kotlin/api-docs/protobuf-kotlin/com.google.protobuf.kotlin/-dsl-list/_index.md
@@ -12,9 +12,9 @@ A simple wrapper around a
 with an extra generic parameter that can be used to disambiguate extension
 methods.
 
-
    This class is used by Kotlin protocol buffer extensions, and its constructor
-is public only because generated message code is in a different compilation
-unit. Others should not use this class directly in any way.
+
    This class is used by Kotlin Protobuf extensions, and its constructor is
+public only because generated message code is in a different compilation unit.
+Others should not use this class directly in any way.
 
 ## Constructors
 
diff --git a/content/reference/kotlin/api-docs/protobuf-kotlin/com.google.protobuf.kotlin/-dsl-map/_index.md b/content/reference/kotlin/api-docs/protobuf-kotlin/com.google.protobuf.kotlin/-dsl-map/_index.md
index 30b83d8ba..c1885aa6e 100644
--- a/content/reference/kotlin/api-docs/protobuf-kotlin/com.google.protobuf.kotlin/-dsl-map/_index.md
+++ b/content/reference/kotlin/api-docs/protobuf-kotlin/com.google.protobuf.kotlin/-dsl-map/_index.md
@@ -14,9 +14,9 @@ A simple wrapper around a
 with an extra generic parameter that can be used to disambiguate extension
 methods.
 
-
    This class is used by Kotlin protocol buffer extensions, and its constructor
-is public only because generated message code is in a different compilation
-unit. Others should not use this class directly in any way.
+
    This class is used by Kotlin Protobuf extensions, and its constructor is
+public only because generated message code is in a different compilation unit.
+Others should not use this class directly in any way.
 
 ## Constructors
 
diff --git a/content/reference/kotlin/api-docs/protobuf-kotlin/com.google.protobuf.kotlin/-proto-dsl-marker/_index.md b/content/reference/kotlin/api-docs/protobuf-kotlin/com.google.protobuf.kotlin/-proto-dsl-marker/_index.md
index 6b1708523..52505497b 100644
--- a/content/reference/kotlin/api-docs/protobuf-kotlin/com.google.protobuf.kotlin/-proto-dsl-marker/_index.md
+++ b/content/reference/kotlin/api-docs/protobuf-kotlin/com.google.protobuf.kotlin/-proto-dsl-marker/_index.md
@@ -10,7 +10,7 @@
 
 annotation class [ProtoDslMarker]()
 
-Indicates an API that is part of a DSL to generate protocol buffer messages.
+Indicates an API that is part of a DSL to generate Protobuf messages.
 
 ## Constructors
 
diff --git a/content/reference/kotlin/kotlin-generated.md b/content/reference/kotlin/kotlin-generated.md
index 746b70e58..43dc54157 100644
--- a/content/reference/kotlin/kotlin-generated.md
+++ b/content/reference/kotlin/kotlin-generated.md
@@ -2,7 +2,7 @@
 title = "Kotlin Generated Code Guide"
 weight = 680
 linkTitle = "Generated Code Guide"
-description = "Describes exactly what Kotlin code the protocol buffer compiler generates for any given protocol definition, in addition to the code generated for Java."
+description = "Describes exactly what Kotlin code the Protobuf compiler generates for any given protocol definition, in addition to the code generated for Java."
 type = "docs"
 +++
 
@@ -17,7 +17,7 @@ before reading this document.
 
 ## Compiler Invocation {#invocation}
 
-The protocol buffer compiler produces Kotlin code that builds on top of Java
+The Protobuf compiler produces Kotlin code that builds on top of Java
 code. As a result, it must be invoked with two command-line flags, `--java_out=`
 and `--kotlin_out=`. The parameter to the `--java_out=` option is the directory
 where you want the compiler to write your Java output, and the same for the
@@ -50,8 +50,8 @@ protoc --proto_path=src --java_out=build/gen/java --kotlin_out=build/gen/kotlin
 ```
 
 If `foo.proto`'s Java package is `com.example` and it contains a message named
-`Bar`, then the protocol buffer compiler will generate the file
-`build/gen/kotlin/com/example/BarKt.kt`. The protocol buffer compiler will
+`Bar`, then the Protobuf compiler will generate the file
+`build/gen/kotlin/com/example/BarKt.kt`. The Protobuf compiler will
 automatically create the `build/gen/kotlin/com` and
 `build/gen/kotlin/com/example` directories if needed. However, it will not
 create `build/gen/kotlin`, `build/gen`, or `build`; they must already exist. You
@@ -66,7 +66,7 @@ Given a simple message declaration:
 message FooBar {}
 ```
 
-The protocol buffer compiler generates—in addition to the generated Java
+The Protobuf compiler generates—in addition to the generated Java
 code—an object called `FooBarKt`, as well as two top-level functions,
 having the following structure:
 
@@ -106,10 +106,10 @@ inline fun Foo.Bar.copy(block: FooKt.BarKt.Dsl.() -> Unit): Foo.Bar
 
 ## Fields
 
-In addition to the methods described in the previous section, the protocol
-buffer compiler generates mutable properties in the DSL for each field defined
-within the message in the `.proto` file. (Kotlin already infers read-only
-properties on the message object from the getters generated by Java.)
+In addition to the methods described in the previous section, the Protobuf
+compiler generates mutable properties in the DSL for each field defined within
+the message in the `.proto` file. (Kotlin already infers read-only properties on
+the message object from the getters generated by Java.)
 
 Note that properties always use camel-case naming, even if the field name in the
 `.proto` file uses lower-case with underscores
@@ -124,7 +124,7 @@ case-conversion works as follows:
 Thus, the field `foo_bar_baz` becomes `fooBarBaz`.
 
 In a few special cases in which a field name conflicts with reserved words in
-Kotlin or methods already defined in the protobuf library, an extra underscore
+Kotlin or methods already defined in the Protobuf library, an extra underscore
 is appended. For instance, the clearer for a field named `in` is `clearIn_()`.
 
 ### Singular Fields
@@ -274,7 +274,7 @@ message Foo {
 }
 ```
 
-The protocol buffer compiler will add the following methods to `FooKt.Dsl`:
+The Protobuf compiler will add the following methods to `FooKt.Dsl`:
 
 -   `operator fun  get(extension: ExtensionLite): T`: gets the
     current value of the extension field in the DSL
diff --git a/content/reference/objective-c/_index.md b/content/reference/objective-c/_index.md
index 8ef6e6014..88ece7858 100644
--- a/content/reference/objective-c/_index.md
+++ b/content/reference/objective-c/_index.md
@@ -2,6 +2,6 @@
 title = "Objective-C Reference"
 weight = 700
 linkTitle = "Objective-C"
-description = "Reference documentation for working with protocol buffer classes in Objective-C."
+description = "Reference documentation for working with Protobuf classes in Objective-C."
 type = "docs"
 +++
diff --git a/content/reference/objective-c/objective-c-generated.md b/content/reference/objective-c/objective-c-generated.md
index 1679d4704..1609f50f2 100644
--- a/content/reference/objective-c/objective-c-generated.md
+++ b/content/reference/objective-c/objective-c-generated.md
@@ -2,7 +2,7 @@
 title = "Objective-C Generated Code Guide"
 weight = 710
 linkTitle = "Generated Code Guide"
-description = "Describes exactly what Objective-C code the protocol buffer compiler generates for any given protocol definition."
+description = "Describes exactly what Objective-C code the Protobuf compiler generates for any given protocol definition."
 type = "docs"
 +++
 
@@ -17,7 +17,7 @@ before reading this document.
 
 ## Compiler invocation {#invocation}
 
-The protocol buffer compiler produces Objective-C output when invoked with the
+The Protobuf compiler produces Objective-C output when invoked with the
 `--objc_out=` command-line flag. The parameter to the `--objc_out=` option is
 the directory where you want the compiler to write your Objective-C output. The
 compiler creates a header file and an implementation file for each `.proto` file
@@ -46,9 +46,9 @@ will *not* create `build` or `build/gen`; they must already exist.
 
 ## Packages {#package}
 
-The Objective-C code generated by the protocol buffer compiler is completely
-unaffected by the package name defined in the `.proto` file, as Objective-C has
-no language-enforced namespacing. Instead, Objective-C class names are
+The Objective-C code generated by the Protobuf compiler is completely unaffected
+by the package name defined in the `.proto` file, as Objective-C has no
+language-enforced namespacing. Instead, Objective-C class names are
 distinguished using prefixes, which you can find out about in the next section.
 
 ## Class prefix {#prefix}
@@ -94,7 +94,7 @@ Given a simple message declaration:
 message Foo {}
 ```
 
-The protocol buffer compiler generates a class called `Foo`. If you specify an
+The Protobuf compiler generates a class called `Foo`. If you specify an
 [`objc_class_prefix` file option](#prefix), the value of this option is
 prepended to the generated class name.
 
@@ -187,9 +187,9 @@ or loop over them as an array.
 
 ## Fields
 
-The following sections describe the code generated by the protocol buffer
-compiler for message fields. They are divided by those with implicit and
-explicit presence. You can learn more about this distinction in
+The following sections describe the code generated by the Protobuf compiler for
+message fields. They are divided by those with implicit and explicit presence.
+You can learn more about this distinction in
 [Field Presence](/programming-guides/field_presence).
 
 
@@ -488,17 +488,17 @@ where `a` will be automatically created via the accessors if necessary. If
 
 ### Repeated fields {#repeated}
 
-Like singular fields ([proto2](#singular2) [proto3](#singular3)), the protocol
-buffer compiler generates one data property for each repeated field. This data
-property is a `GPBArray` depending on the field type where `` can
-be one of `UInt32`, `Int32`, `UInt64`, `Int64`, `Bool`, `Float`, `Double`, or
-`Enum`. `NSMutableArray` will be used for `string`, `bytes` and `message` types.
-Field names for repeated types have `Array` appended to them. The reason for
-appending `Array` in the Objective-C interface is to make the code more
-readable. Repeated fields in proto files tend to have singular names which do
-not read well in standard Objective-C usage. Making the singular names plural
-would be more idiomatic Objective-C, however pluralization rules are too complex
-to support in the compiler.
+Like singular fields ([proto2](#singular2) [proto3](#singular3)), the Protobuf
+compiler generates one data property for each repeated field. This data property
+is a `GPBArray` depending on the field type where `` can be one of
+`UInt32`, `Int32`, `UInt64`, `Int64`, `Bool`, `Float`, `Double`, or `Enum`.
+`NSMutableArray` will be used for `string`, `bytes` and `message` types. Field
+names for repeated types have `Array` appended to them. The reason for appending
+`Array` in the Objective-C interface is to make the code more readable. Repeated
+fields in proto files tend to have singular names which do not read well in
+standard Objective-C usage. Making the singular names plural would be more
+idiomatic Objective-C, however pluralization rules are too complex to support in
+the compiler.
 
 ```proto
 message Foo {
@@ -699,7 +699,7 @@ message Order {
 };
 ```
 
-The protocol buffer compiler generates:
+The Protobuf compiler generates:
 
 ```objc
 typedef GPB_ENUM(Order_OrderID_OneOfCase) {
@@ -948,7 +948,7 @@ the generated code will be:
 ```objc
 // The generated enum value name will be the enumeration name followed by
 // an underscore and then the enumerator name converted to camel case.
-// GPB_ENUM is a macro defined in the Objective-C Protocol Buffer headers
+// GPB_ENUM is a macro defined in the Objective-C Protobuf headers
 // that enforces all enum values to be int32 and aids in Swift Enumeration
 // support.
 typedef GPB_ENUM(Foo) {
@@ -1079,7 +1079,7 @@ potentially dead strip them.
 Apple documents how they import Objective-C enumerations to Swift enumerations
 in
 [Interacting with C APIs](https://developer.apple.com/library/ios/documentation/Swift/Conceptual/BuildingCocoaApps/InteractingWithCAPIs.html#//apple_ref/doc/uid/TP40014216-CH8-XID_11).
-Protocol buffer-generated enumerations support Objective-C to Swift conversions.
+Protobuf-generated enumerations support Objective-C to Swift conversions.
 
 ```proto
 // Proto
@@ -1108,13 +1108,13 @@ let anotherValue: Foo = .GPBUnrecognizedEnumeratorValue
 
 ## Well-known types {#wellknown}
 
-If you use any of the message types provided with protocol buffers, they will in
-general just use their proto definitions in generated Objective-C code, though
-we supply some basic conversion methods in categories to make using them
-simpler. Note that we do not have special APIs for all well-known types yet,
-including [`Any`](/programming-guides/proto3#any) (there
-is currently no helper method to convert an `Any`'s message value into a message
-of the appropriate type).
+If you use any of the message types provided with Protobuf, they will in general
+just use their proto definitions in generated Objective-C code, though we supply
+some basic conversion methods in categories to make using them simpler. Note
+that we do not have special APIs for all well-known types yet, including
+[`Any`](/programming-guides/proto3#any) (there is
+currently no helper method to convert an `Any`'s message value into a message of
+the appropriate type).
 
 ### Time Stamps
 
@@ -1180,7 +1180,7 @@ The compiler generates the following:
 
 // The base class provides:
 //   + (GPBExtensionRegistry *)extensionRegistry;
-// which is an GPBExtensionRegistry that includes all the extensions defined by
+// which is a GPBExtensionRegistry that includes all the extensions defined by
 // this file and all files that it depends on.
 
 @end
diff --git a/content/reference/other.md b/content/reference/other.md
index 3db124d62..ad0f2034e 100644
--- a/content/reference/other.md
+++ b/content/reference/other.md
@@ -1,25 +1,24 @@
 +++
 title = "Other Languages"
 weight = 840
-description = "protoc, the Protocol Buffers Compiler, can be extended to support new languages via plugins."
+description = "protoc, the Protobuf Compiler, can be extended to support new languages via plugins."
 type = "docs"
 +++
 
 While the current release includes compilers and APIs for C++, Java, Go, Ruby,
 C\#, and Python, the compiler code is designed so that it's easy to add support
 for other languages. There are several ongoing projects to add new language
-implementations to Protocol Buffers, including C, Haskell, Perl, Rust, and more.
+implementations to Protobuf, including C, Haskell, Perl, Rust, and more.
 
 For a list of links to projects we know about, see the
 [third-party add-ons wiki page](https://github.com/protocolbuffers/protobuf/blob/main/docs/third_party.md).
 
 ## Compiler Plugins {#plugins}
 
-`protoc`, the Protocol Buffers Compiler, can be extended to support new
-languages via plugins. A plugin is just a program which reads a
-`CodeGeneratorRequest` protocol buffer from standard input and then writes a
-`CodeGeneratorResponse` protocol buffer to standard output. These message types
-are defined in
+`protoc`, the Protobuf Compiler, can be extended to support new languages via
+plugins. A plugin is just a program which reads a `CodeGeneratorRequest`
+Protobuf message from standard input and then writes a `CodeGeneratorResponse`
+Protobuf message to standard output. These message types are defined in
 [`plugin.proto`](/reference/cpp/api-docs/google.protobuf.compiler.plugin.pb).
 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
diff --git a/content/reference/php/_index.md b/content/reference/php/_index.md
index a2f9f457e..3c55b5b15 100644
--- a/content/reference/php/_index.md
+++ b/content/reference/php/_index.md
@@ -2,6 +2,6 @@
 title = "PHP Reference"
 weight = 720
 linkTitle = "PHP"
-description = "Reference documentation for working with protocol buffer classes in PHP."
+description = "Reference documentation for working with Protobuf classes in PHP."
 type = "docs"
 +++
diff --git a/content/reference/php/php-generated.md b/content/reference/php/php-generated.md
index 957132899..3a5007145 100644
--- a/content/reference/php/php-generated.md
+++ b/content/reference/php/php-generated.md
@@ -2,25 +2,25 @@
 title = "PHP Generated Code Guide"
 weight = 730
 linkTitle = "Generated Code Guide"
-description = "Describes the PHP code that the protocol buffer compiler generates for any given protocol definition."
+description = "Describes the PHP code that the Protobuf compiler generates for any given protocol definition."
 type = "docs"
 +++
 
 You should read the
 [proto3 language guide](/programming-guides/proto3) or
 [Editions language guide](/programming-guides/editions)
-before reading this document. Note that the protocol buffer compiler currently
-only supports proto3 and editions code generation for PHP.
+before reading this document. Note that the Protobuf compiler currently only
+supports proto3 and editions code generation for PHP.
 
 ## Compiler Invocation {#invocation}
 
-The protocol buffer compiler produces PHP output when invoked with the
-`--php_out=` command-line flag. The parameter to the `--php_out=` option is the
-directory where you want the compiler to write your PHP output. In order to
-conform to PSR-4, the compiler creates a sub-directory corresponding to the
-package defined in the proto file. In addition, for each message in the proto
-file input the compiler creates a separate file in the package's subdirectory.
-The names of the output files of messages are composed of three parts:
+The Protobuf compiler produces PHP output when invoked with the `--php_out=`
+command-line flag. The parameter to the `--php_out=` option is the directory
+where you want the compiler to write your PHP output. In order to conform to
+PSR-4, the compiler creates a sub-directory corresponding to the package defined
+in the proto file. In addition, for each message in the proto file input the
+compiler creates a separate file in the package's subdirectory. The names of the
+output files of messages are composed of three parts:
 
 -   Base directory: The proto path (specified with the `--proto_path=` or `-I`
     command-line flag) is replaced with the output path (specified with the
@@ -97,10 +97,10 @@ message Foo {
 }
 ```
 
-The protocol buffer compiler generates a PHP class called `Foo`. This class
-inherits from a common base class, `Google\Protobuf\Internal\Message`, which
-provides methods for encoding and decoding your message types, as shown in the
-following example:
+The Protobuf compiler generates a PHP class called `Foo`. This class inherits
+from a common base class, `Google\Protobuf\Internal\Message`, which provides
+methods for encoding and decoding your message types, as shown in the following
+example:
 
 ```php
 $from = new Foo();
@@ -156,9 +156,9 @@ specified, it is prepended to all generated message classes.
 
 ## Fields
 
-For each field in a message type, the protocol buffer compiler generates a set
-of accessor methods to set and get the field. The accessor methods are named
-using `snake_case` field names converted to `PascalCase`. So, given a field
+For each field in a message type, the Protobuf compiler generates a set of
+accessor methods to set and get the field. The accessor methods are named using
+`snake_case` field names converted to `PascalCase`. So, given a field
 `field_name`, the accessor methods will be `getFieldName` and `setFieldName`.
 
 ```php
@@ -181,8 +181,7 @@ integer, float, and numeric strings. Conversions that are not permitted include
 all conversions to/from arrays or objects. Float to integer overflow conversions
 are undefined.
 
-You can see the corresponding PHP type for each scalar protocol buffers type in
-the
+You can see the corresponding PHP type for each scalar Protobuf type in the
 [scalar value types table](/programming-guides/proto3#scalar).
 
 ### `has...` and `clear...`
@@ -220,8 +219,8 @@ held elsewhere (for example, as a field value on another message).
 
 ### Repeated Fields
 
-The protocol buffer compiler generates a special `RepeatedField` for each
-repeated field. So, for example, given the following field:
+The Protobuf compiler generates a special `RepeatedField` for each repeated
+field. So, for example, given the following field:
 
 ```proto
 repeated int32 foo = 1;
@@ -236,8 +235,8 @@ $m->setFoo($array);
 
 ### Map Fields
 
-The protocol buffer compiler generates a `MapField` for each map field. So given
-this field:
+The Protobuf compiler generates a `MapField` for each map field. So given this
+field:
 
 ```proto
 map weight = 1;
@@ -251,8 +250,8 @@ $m->getWeight()[1] = 1;
 
 ## Enumerations {#enum}
 
-PHP doesn't have native enums, so instead the protocol buffer compiler generates
-a PHP class for each enum type in your `.proto` file, just like for
+PHP doesn't have native enums, so instead the Protobuf compiler generates a PHP
+class for each enum type in your `.proto` file, just like for
 [messages](#message), with constants defined for each value. So, given this
 enum:
 
@@ -295,9 +294,9 @@ specified, it is prepended to all generated enum classes.
 ## Oneof
 
 For a [oneof](/programming-guides/editions#oneof), the
-protocol buffer compiler generates a `has` and `clear` method for each field in
-the oneof, as well as a special accessor method that lets you find out which
-oneof field (if any) is set. So, given this message:
+Protobuf compiler generates a `has` and `clear` method for each field in the
+oneof, as well as a special accessor method that lets you find out which oneof
+field (if any) is set. So, given this message:
 
 ```proto
 message TestMessage {
diff --git a/content/reference/protobuf/_index.md b/content/reference/protobuf/_index.md
index b28b99303..76d04cb81 100644
--- a/content/reference/protobuf/_index.md
+++ b/content/reference/protobuf/_index.md
@@ -1,7 +1,7 @@
 +++
-title = "Protocol Buffers Reference"
+title = "Protobuf Reference"
 weight = 790
-linkTitle = "Protocol Buffers"
-description = "Language-agnostic information about how to use protocol buffers."
+linkTitle = "Protobuf"
+description = "Language-agnostic information about how to use Protobuf."
 type = "docs"
 +++
diff --git a/content/reference/protobuf/edition-2023-spec.md b/content/reference/protobuf/edition-2023-spec.md
index 535e353d2..991c5febd 100644
--- a/content/reference/protobuf/edition-2023-spec.md
+++ b/content/reference/protobuf/edition-2023-spec.md
@@ -1,8 +1,8 @@
 +++
-title = "Protocol Buffers Edition 2023 Language Specification"
+title = "Protobuf Edition 2023 Language Specification"
 weight = 800
 linkTitle = "2023 Language Specification"
-description = "Language specification reference for edition 2023 of the Protocol Buffers language."
+description = "Language specification reference for edition 2023 of the Protobuf language."
 type = "docs"
 +++
 
@@ -146,7 +146,7 @@ package foo.bar;
 ## Option
 
 Options can be used in proto files, messages, enums and services. An option can
-be a protobuf defined option or a custom option. For more information, see
+be a Protobuf defined option or a custom option. For more information, see
 [Options](/programming-guides/proto2#options) in the
 language guide. Options are also be used to control
 [Feature Settings](/editions/features).
@@ -165,7 +165,7 @@ option features.enum_type = CLOSED;
 
 ## Fields
 
-Fields are the basic elements of a protocol buffer message. Fields can be normal
+Fields are the basic elements of a Protobuf message. Fields can be normal
 fields, group fields, oneof fields, or map fields. A field has a label, type and
 field number.
 
diff --git a/content/reference/protobuf/edition-2024-spec.md b/content/reference/protobuf/edition-2024-spec.md
index 9e5a8f5f6..931d22418 100644
--- a/content/reference/protobuf/edition-2024-spec.md
+++ b/content/reference/protobuf/edition-2024-spec.md
@@ -1,8 +1,8 @@
 +++
-title = "Protocol Buffers Edition 2024 Language Specification"
+title = "Protobuf Edition 2024 Language Specification"
 weight = 801
 linkTitle = "2024 Language Specification"
-description = "Language specification reference for edition 2024 of the Protocol Buffers language."
+description = "Language specification reference for edition 2024 of the Protobuf language."
 type = "docs"
 +++
 
@@ -147,7 +147,7 @@ package foo.bar;
 ## Option
 
 Options can be used in proto files, messages, enums and services. An option can
-be a protobuf defined option or a custom option. For more information, see
+be a Protobuf defined option or a custom option. For more information, see
 [Options](/programming-guides/proto2#options) in the
 language guide. Options are also be used to control
 [Feature Settings](/editions/features).
@@ -166,7 +166,7 @@ option features.enum_type = CLOSED;
 
 ## Fields
 
-Fields are the basic elements of a protocol buffer message. Fields can be normal
+Fields are the basic elements of a Protobuf message. Fields can be normal
 fields, group fields, oneof fields, or map fields. A field has a label, type and
 field number.
 
diff --git a/content/reference/protobuf/google.protobuf.md b/content/reference/protobuf/google.protobuf.md
index ffac4498c..28d5445e6 100644
--- a/content/reference/protobuf/google.protobuf.md
+++ b/content/reference/protobuf/google.protobuf.md
@@ -1,5 +1,5 @@
 +++
-title = "Protocol Buffers Well-Known Types"
+title = "Protobuf Well-Known Types"
 weight = 830
 linkTitle = "Well-Known Types"
 description = "API documentation for the google.protobuf package."
@@ -121,7 +121,7 @@ custom JSON in addition to the `@type` field. Example (for message
 
 ## Api {#api}
 
-Api is a light-weight descriptor for a protocol buffer service.
+Api is a light-weight descriptor for a Protobuf service.
 
 
@@ -194,7 +194,7 @@ Api is a light-weight descriptor for a protocol buffer service.
         >
       
@@ -417,7 +417,7 @@ Enum type definition
       
-      
+      
@@ -470,7 +470,7 @@ Enum value definition.
       
-      
+      
    
   
       
    
-        Source context for the protocol buffer service represented by this
+        Source context for the Protobuf service represented by this
         message.
       
     
    
         Option
       Protocol buffer options.Protobuf options.
     
    
     
    
       source_context
         Option
       Protocol buffer options.Protobuf options.
     
    
   
 
    
@@ -540,7 +540,7 @@ A single field of a message type.
       
    		
         Option
       The protocol buffer options.The Protobuf options.
     
    
     
    
       json_name
    
@@ -1141,7 +1140,7 @@ enumeration, etc.
 
 ## SourceContext {#source-context}
 
-`SourceContext` represents information about the source of a protobuf element,
+`SourceContext` represents information about the source of a Protobuf element,
 like the file in which it is defined.
 
 
    
   
    
@@ -1158,7 +1157,7 @@ like the file in which it is defined.
       
@@ -1219,7 +1218,7 @@ The JSON representation for `Struct` is JSON object.
 
 ## Syntax {#syntax}
 
-The syntax in which a protocol buffer element is defined.
+The syntax in which a Protobuf element is defined.
 
 
    string
       
         The path-qualified name of the .proto file that contained the associated
-        protobuf element. For example:
+        Protobuf element. For example:
         "google/protobuf/source.proto".
       
     
    
@@ -1348,7 +1347,7 @@ timestamp = Timestamp(seconds=seconds, nanos=nanos)
 
 ## Type {#type}
 
-A protocol buffer message type.
+A Protobuf message type.
 
 
    
   
    
@@ -1384,7 +1383,7 @@ A protocol buffer message type.
       
-      
+      
diff --git a/content/reference/protobuf/mime-types.md b/content/reference/protobuf/mime-types.md
index b290d4a19..2652ad7dd 100644
--- a/content/reference/protobuf/mime-types.md
+++ b/content/reference/protobuf/mime-types.md
@@ -1,5 +1,5 @@
 +++
-title = "Protocol Buffer MIME Types"
+title = "Protobuf MIME Types"
 weight = 830
 linkTitle = "MIME Types"
 description = "Standard MIME types for Protobuf Serializations."
@@ -30,7 +30,7 @@ followed by the following parameters:
 -   Protobuf reserves the `version` parameter for potential future versioning of
     our wire formats. Do not set it until a wire format is versioned.
 
-So the standard MIME types for common protobuf encodings are:
+So the standard MIME types for common Protobuf encodings are:
 
 -   `application/protobuf` for serialized binary protos.
 -   `application/protobuf+json; charset=utf-8` for JSON format protos.
@@ -43,7 +43,7 @@ unknown or illegal values.
 
 When binary protos are transacted over HTTP, Protobuf strongly recommends
 Base64-encoding them and setting `X-Content-Type-Options: nosniff` to prevent
-XSS, as it is possible for a Protobuf to parse as active content.
+XSS, as it is possible for a proto to parse as active content.
 
 It is acceptable to pass additional parameters to these MIME types if desired,
 such as a type URL which indicates the content schema; but the MIME type
diff --git a/content/reference/protobuf/proto2-spec.md b/content/reference/protobuf/proto2-spec.md
index 7037ab7dc..a48212248 100644
--- a/content/reference/protobuf/proto2-spec.md
+++ b/content/reference/protobuf/proto2-spec.md
@@ -1,5 +1,5 @@
 +++
-title = "Protocol Buffers Language Specification (Proto2 Syntax)"
+title = "Protobuf Language Specification (Proto2 Syntax)"
 weight = 800
 linkTitle = "Language Specification (Proto2 Syntax)"
 description = "Language specification reference for the proto2 syntax and its relationship to Protobuf Editions."
@@ -110,7 +110,7 @@ constant = fullIdent | ( [ "-" | "+" ] intLit ) | ( [ "-" | "+" ] floatLit ) |
 
 ## Syntax
 
-The syntax statement is used to define the protobuf version. If `syntax` is
+The syntax statement is used to define the Protobuf version. If `syntax` is
 omitted, the protocol compiler will use `proto2`. For the sake of clarity, it's
 recommended to always explicitly include a `syntax` statement in your `.proto`
 files.
@@ -151,7 +151,7 @@ package foo.bar;
 ## Option
 
 Options can be used in proto files, messages, enums and services. An option can
-be a protobuf defined option or a custom option. For more information, see
+be a Protobuf defined option or a custom option. For more information, see
 [Options](/programming-guides/proto2#options) in the
 language guide.
 
@@ -169,7 +169,7 @@ option java_package = "com.example.foo";
 
 ## Fields
 
-Fields are the basic elements of a protocol buffer message. Fields can be normal
+Fields are the basic elements of a Protobuf message. Fields can be normal
 fields, group fields, oneof fields, or map fields. A field has a type, name, and
 field number. In proto2, fields also have a label (`required`, `optional`, or
 `repeated`).
diff --git a/content/reference/protobuf/proto3-spec.md b/content/reference/protobuf/proto3-spec.md
index c025a934d..9ff637993 100644
--- a/content/reference/protobuf/proto3-spec.md
+++ b/content/reference/protobuf/proto3-spec.md
@@ -1,8 +1,8 @@
 +++
-title = "Protocol Buffers Language Specification (Proto3)"
+title = "Protobuf Language Specification (Proto3)"
 weight = 810
 linkTitle = "Language Specification (Proto3)"
-description = "Language specification reference for the Protocol Buffers language (Proto3)."
+description = "Language specification reference for the Protobuf language (Proto3)."
 type = "docs"
 +++
 
@@ -107,7 +107,7 @@ constant = fullIdent | ( [ "-" | "+" ] intLit ) | ( [ "-" | "+" ] floatLit ) |
 
 ## Syntax
 
-The syntax statement is used to define the protobuf version.
+The syntax statement is used to define the Protobuf version.
 
 ```
 syntax = "syntax" "=" ("'" "proto3" "'" | '"' "proto3" '"') ";"
@@ -151,7 +151,7 @@ package foo.bar;
 ## Option
 
 Options can be used in proto files, messages, enums and services. An option can
-be a protobuf defined option or a custom option. For more information, see
+be a Protobuf defined option or a custom option. For more information, see
 [Options](/programming-guides/proto3#options) in the
 language guide.
 
@@ -170,7 +170,7 @@ option java_package = "com.example.foo";
 
 ## Fields
 
-Fields are the basic elements of a protocol buffer message. Fields can be normal
+Fields are the basic elements of a Protobuf message. Fields can be normal
 fields, oneof fields, or map fields. A field has a type and field number.
 
 ```
diff --git a/content/reference/protobuf/textformat-spec.md b/content/reference/protobuf/textformat-spec.md
index dbb997bee..e64bba667 100644
--- a/content/reference/protobuf/textformat-spec.md
+++ b/content/reference/protobuf/textformat-spec.md
@@ -1,7 +1,7 @@
 +++
 title = "Text Format Language Specification"
 weight = 820
-description = "The protocol buffer Text Format Language specifies a syntax for representation of protobuf data in text form, which is often useful for configurations or tests."
+description = "The Protobuf Text Format Language specifies a syntax for representation of Protobuf data in text form, which is often useful for configurations or tests."
 type = "docs"
 +++
 
@@ -517,7 +517,7 @@ integer         = signedInteger | unsignedInteger ;
         -0x80000000 to 0x7FFFFFFF containing an enum
         value number. It is not valid to specify a name that is not a
         member of the field's enum type definition. Depending on
-        the particular protobuf runtime implementation, it may or may not be
+        the particular Protobuf runtime implementation, it may or may not be
         valid to specify a number that is not a member of the field's
         enum type definition. Text format processors not tied to a
         particular runtime implementation (such as IDE support) may choose to
@@ -733,7 +733,7 @@ as `.protoascii` wrongly imply that text format is ascii-only, and others like
 tooling. {{% /alert %}}
 
 ```textproto
-# This is an example of Protocol Buffer's text format.
+# This is an example of Protobuf's text format.
 # Unlike .proto files, only shell-style line comments are supported.
 
 name: "John Smith"
@@ -766,7 +766,7 @@ the schema, so they may provide various features.
 
 ## Working with the Format Programmatically
 
-Due to how individual Protocol Buffer implementations
+Due to how individual Protobuf implementations
 emit neither a consistent nor canonical text format,
 tools or libraries that modify TextProto files or emit TextProto output must
 explicitly use
diff --git a/content/reference/python/_index.md b/content/reference/python/_index.md
index f5db62f67..f1923c7d7 100644
--- a/content/reference/python/_index.md
+++ b/content/reference/python/_index.md
@@ -2,6 +2,6 @@
 title = "Python Reference"
 weight = 740
 linkTitle = "Python"
-description = "Reference documentation for working with protocol buffer classes in Python."
+description = "Reference documentation for working with Protobuf classes in Python."
 type = "docs"
 +++
diff --git a/content/reference/python/python-comparison.md b/content/reference/python/python-comparison.md
index 48c66f774..586eca4b5 100644
--- a/content/reference/python/python-comparison.md
+++ b/content/reference/python/python-comparison.md
@@ -11,18 +11,18 @@ representation of a proto message instance to determine if its content is the
 same as another instance. A subset of the ways that a wire-format proto message
 instance can vary include the following:
 
-*   The protobuf schema changes in certain ways.
+*   The Protobuf schema changes in certain ways.
 *   A map field stores its values in a different order.
 *   The binary is built with different flags (such as opt vs. debug).
-*   The protobuf library is updated.
+*   The Protobuf library is updated.
 
 Because of these ways that serialized data can vary, determining equality
 involves other methods.
 
 ## Comparison Methods {#methods}
 
-You can compare protocol buffer messages for equality using the standard Python
-`==` operator. Comparing two objects using the `==` operator compares with
+You can compare Protobuf messages for equality using the standard Python `==`
+operator. Comparing two objects using the `==` operator compares with
 `message.ListFields()`. When testing, you can use `self.assertEqual(msg1,
 msg2)`.
 
@@ -74,7 +74,7 @@ be tracked, the field is always compared by its value against the corresponding
 field in the other message.
 
 This behavior, where presence is part of the equality check, is different from
-how some other languages or protobuf libraries might handle equality, where
+how some other languages or Protobuf libraries might handle equality, where
 unset fields and fields set to their default value are sometimes treated as
 equivalent (often for wire-format compatibility). In Python, `==` performs a
 stricter check.
diff --git a/content/reference/python/python-generated.md b/content/reference/python/python-generated.md
index 49ed24699..0ee1bed93 100644
--- a/content/reference/python/python-generated.md
+++ b/content/reference/python/python-generated.md
@@ -2,7 +2,7 @@
 title = "Python Generated Code Guide"
 weight = 750
 linkTitle = "Generated Code Guide"
-description = "Describes exactly what Python definitions the protocol buffer compiler generates for any given protocol definition."
+description = "Describes exactly what Python definitions the Protobuf compiler generates for any given protocol definition."
 type = "docs"
 +++
 
@@ -16,16 +16,16 @@ across all versions. You should read the
 and/or [Editions guide](/programming-guides/editions)
 before reading this document.
 
-The Python Protocol Buffers implementation is a little different from C++ and
-Java. In Python, the compiler only outputs code to build descriptors for the
-generated classes, and a
+The Python Protobuf implementation is a little different from C++ and Java. In
+Python, the compiler only outputs code to build descriptors for the generated
+classes, and a
 [Python metaclass](https://docs.python.org/2.7/reference/datamodel#metaclasses)
 does the real work. This document describes what you get *after* the metaclass
 has been applied.
 
 ## Compiler Invocation {#invocation}
 
-The protocol buffer compiler produces Python output when invoked with the
+The Protobuf compiler produces Python output when invoked with the
 `--python_out=` command-line flag. The parameter to the `--python_out=` option
 is the directory where you want the compiler to write your Python output. The
 compiler creates a `.py` file for each `.proto` file input. The names of the
@@ -57,27 +57,27 @@ with underscores. So, the file `foo-bar.proto` becomes the Python file
 `foo_bar_pb2.py`.
 
 {{% alert title="Tip" color="note" %}} When
-outputting Python code, the protocol buffer compiler's ability to output
-directly to ZIP archives is particularly convenient, as the Python interpreter
-is able to read directly from these archives if placed in the `PYTHONPATH`. To
-output to a ZIP file, simply provide an output location ending in `.zip`.
-{{% /alert %}}
+outputting Python code, the Protobuf compiler's ability to output directly to
+ZIP archives is particularly convenient, as the Python interpreter is able to
+read directly from these archives if placed in the `PYTHONPATH`. To output to a
+ZIP file, simply provide an output location ending in
+`.zip`. {{% /alert %}}
 
 {{% alert title="Note" color="note" %}}
-The number 2 in the extension `_pb2.py` designates version 2 of Protocol
-Buffers. Version 1 was used primarily inside Google, though you might be able to
-find parts of it included in other Python code that was released before Protocol
-Buffers. Since version 2 of Python Protocol Buffers has a completely different
-interface, and since Python does not have compile-time type checking to catch
-mistakes, we chose to make the version number be a prominent part of generated
-Python file names. Currently proto2, proto3, and Editions all use `_pb2.py` for
-their generated files. {{% /alert %}}
+The number 2 in the extension `_pb2.py` designates version 2 of Protobuf.
+Version 1 was used primarily inside Google, though you might be able to find
+parts of it included in other Python code that was released before Protobuf.
+Since version 2 of Python Protobuf has a completely different interface, and
+since Python does not have compile-time type checking to catch mistakes, we
+chose to make the version number be a prominent part of generated Python file
+names. Currently proto2, proto3, and Editions all use `_pb2.py` for their
+generated files. {{% /alert %}}
 
 ## Packages {#package}
 
-The Python code generated by the protocol buffer compiler is completely
-unaffected by the package name defined in the `.proto` file. Instead, Python
-packages are identified by directory structure.
+The Python code generated by the Protobuf compiler is completely unaffected by
+the package name defined in the `.proto` file. Instead, Python packages are
+identified by directory structure.
 
 ## Messages {#message}
 
@@ -87,7 +87,7 @@ Given a simple message declaration:
 message Foo {}
 ```
 
-The protocol buffer compiler generates a class called `Foo`, which subclasses
+The Protobuf compiler generates a class called `Foo`, which subclasses
 [`google.protobuf.Message`](https://googleapis.dev/python/protobuf/latest/google/protobuf/message.html#google.protobuf.message.Message).
 The class is a concrete class; no abstract methods are left unimplemented.
 Unlike C++ and Java, Python generated code is unaffected by the `optimize_for`
@@ -133,11 +133,11 @@ can refer to it as `Foo.Bar`.
 
 ## Well-known Types {#wkt}
 
-Protocol buffers provides a number of
+Protobuf provides a number of
 [well-known types](/reference/protobuf/google.protobuf)
 that you can use in your .proto files along with your own message types. Some
-WKT messages have special methods in addition to the usual protocol buffer
-message methods, as they subclass both
+WKT messages have special methods in addition to the usual Protobuf message
+methods, as they subclass both
 [`google.protobuf.Message`](https://googleapis.dev/python/protobuf/latest/google/protobuf/message.html#google.protobuf.message.Message)
 and a WKT class.
 
@@ -157,13 +157,13 @@ the stored one and returns `False` if they don't match and does not attempt any
 unpacking; `True` otherwise.
 
 You can also call the `Is()` method to check if the Any message represents the
-given protocol buffer type. For example:
+given Protobuf message type. For example:
 
 ```python
 assert any_message.Is(message.DESCRIPTOR)
 ```
 
-Use the `TypeName()` method to retrieve the protobuf type name of an inner
+Use the `TypeName()` method to retrieve the Protobuf type name of an inner
 message.
 
 ### Timestamp {#timestamp}
@@ -284,8 +284,8 @@ If the field's name is a Python keyword, then its property will only be
 accessible via `getattr()` and `setattr()`, as described in the
 [Names that conflict with Python keywords](#keyword-conflicts) section.
 
-Protocol buffers defines two modes of field presence: `explicit` and `implicit`.
-Each of these is described in the following sections.
+Protobuf defines two modes of field presence: `explicit` and `implicit`. Each of
+these is described in the following sections.
 
 ### Singular Fields with Explicit Presence {#singular-explicit}
 
@@ -664,9 +664,9 @@ You can find out more about undefined keys in the next section.
 
 #### Referencing undefined keys {#undefined}
 
-The semantics of Protocol Buffer maps behave slightly differently to Python
-`dict`s when it comes to undefined keys. In a regular Python `dict`, referencing
-an undefined key raises a KeyError exception:
+The semantics of Protobuf maps behave slightly differently to Python `dict`s
+when it comes to undefined keys. In a regular Python `dict`, referencing an
+undefined key raises a KeyError exception:
 
 ```python
 >>> x = {}
@@ -676,8 +676,8 @@ Traceback (most recent call last):
 KeyError: 5
 ```
 
-However, in Protocol Buffers maps, referencing an undefined key creates the key
-in the map with a zero/false/empty value. This behavior is more like the Python
+However, in Protobuf maps, referencing an undefined key creates the key in the
+map with a zero/false/empty value. This behavior is more like the Python
 standard library `defaultdict`.
 
 ```python
@@ -968,10 +968,10 @@ extend Foo {
 }
 ```
 
-The protocol buffer compiler generates an \"extension identifier\" called `bar`.
-The identifier acts as a key to the `Extensions` dictionary. The result of
-looking up a value in this dictionary is exactly the same as if you accessed a
-normal field of the same type. So, given the above example, you could do:
+The Protobuf compiler generates an \"extension identifier\" called `bar`. The
+identifier acts as a key to the `Extensions` dictionary. The result of looking
+up a value in this dictionary is exactly the same as if you accessed a normal
+field of the same type. So, given the above example, you could do:
 
 ```python
 foo = Foo()
@@ -1001,11 +1001,11 @@ If the `.proto` file contains the following line:
 option py_generic_services = true;
 ```
 
-Then the protocol buffer compiler will generate code based on the service
-definitions found in the file as described in this section. However, the
-generated code may be undesirable as it is not tied to any particular RPC
-system, and thus requires more levels of indirection that code tailored to one
-system. If you do NOT want this code to be generated, add this line to the file:
+Then the Protobuf compiler will generate code based on the service definitions
+found in the file as described in this section. However, the generated code may
+be undesirable as it is not tied to any particular RPC system, and thus requires
+more levels of indirection than code tailored to one system. If you do NOT want
+this code to be generated, add this line to the file:
 
 ```proto
 option py_generic_services = false;
@@ -1022,8 +1022,8 @@ to generate code appropriate for the system. These plugins are likely to require
 that abstract services are disabled, so that they can generate their own classes
 of the same names.
 
-The remainder of this section describes what the protocol buffer compiler
-generates when abstract services are enabled.
+The remainder of this section describes what the Protobuf compiler generates
+when abstract services are enabled.
 
 ### Interface {#interface}
 
@@ -1035,9 +1035,9 @@ service Foo {
 }
 ```
 
-The protocol buffer compiler will generate a class `Foo` to represent this
-service. `Foo` will have a method for each method defined in the service
-definition. In this case, the method `Bar` is defined as:
+The Protobuf compiler will generate a class `Foo` to represent this service.
+`Foo` will have a method for each method defined in the service definition. In
+this case, the method `Bar` is defined as:
 
 ```python
 def Bar(self, rpc_controller, request, done)
@@ -1054,8 +1054,8 @@ with an error message indicating that the method is unimplemented, then invoke
 the `done` callback. When implementing your own service, you must subclass this
 generated service and implement its methods as appropriate.
 
-`Foo` subclasses the `Service` interface. The protocol buffer compiler
-automatically generates implementations of the methods of `Service` as follows:
+`Foo` subclasses the `Service` interface. The Protobuf compiler automatically
+generates implementations of the methods of `Service` as follows:
 
 -   `GetDescriptor`: Returns the service's
     [`ServiceDescriptor`](https://googleapis.dev/python/protobuf/latest/google/protobuf/descriptor.html#google.protobuf.descriptor.ServiceDescriptor).
@@ -1066,8 +1066,8 @@ automatically generates implementations of the methods of `Service` as follows:
 
 ### Stub {#stub}
 
-The protocol buffer compiler also generates a \"stub\" implementation of every
-service interface, which is used by clients wishing to send requests to servers
+The Protobuf compiler also generates a \"stub\" implementation of every service
+interface, which is used by clients wishing to send requests to servers
 implementing the service. For the `Foo` service (above), the stub implementation
 `Foo_Stub` will be defined.
 
@@ -1076,7 +1076,7 @@ implementing the service. For the `Foo` service (above), the stub implementation
 as a parameter. The stub then implements each of the service's methods by
 calling the channel's `CallMethod()` method.
 
-The Protocol Buffer library does not include an RPC implementation. However, it
+The Protobuf library does not include an RPC implementation. However, it
 includes all of the tools you need to hook up a generated service class to any
 arbitrary RPC implementation of your choice. You need only provide
 implementations of `RpcChannel` and
@@ -1094,7 +1094,7 @@ the following types using the given insertion point names.
 {{% alert title="Warning" color="warning" %}} Do not
 generate code which relies on private class members declared by the standard
 code generator, as these implementation details may change in future versions of
-Protocol Buffers. {{% /alert %}}
+Protobuf. {{% /alert %}}
 
 ## Sharing Messages Between Python and C++ {#sharing-messages}
 
diff --git a/content/reference/ruby/_index.md b/content/reference/ruby/_index.md
index 65d4ca27c..fe969da87 100644
--- a/content/reference/ruby/_index.md
+++ b/content/reference/ruby/_index.md
@@ -2,6 +2,6 @@
 title = "Ruby Reference"
 weight = 770
 linkTitle = "Ruby"
-description = "Reference documentation for working with protocol buffer classes in Ruby."
+description = "Reference documentation for working with Protobuf classes in Ruby."
 type = "docs"
 +++
diff --git a/content/reference/ruby/ruby-generated.md b/content/reference/ruby/ruby-generated.md
index bef60f3af..f029c5f7d 100644
--- a/content/reference/ruby/ruby-generated.md
+++ b/content/reference/ruby/ruby-generated.md
@@ -2,7 +2,7 @@
 title = "Ruby Generated Code Guide"
 weight = 780
 linkTitle = "Generated Code Guide"
-description = "Describes the API of message objects that the protocol buffer compiler generates for any given protocol definition."
+description = "Describes the API of message objects that the Protobuf compiler generates for any given protocol definition."
 type = "docs"
 +++
 
@@ -15,12 +15,11 @@ this document.
 
 ## Compiler Invocation {#invocation}
 
-The protocol buffer compiler produces Ruby output when invoked with the
-`--ruby_out=` command-line flag. The parameter to the `--ruby_out=` option is
-the directory where you want the compiler to write your Ruby output. The
-compiler creates a `.rb` file for each `.proto` file input. The names of the
-output files are computed by taking the name of the `.proto` file and making two
-changes:
+The Protobuf compiler produces Ruby output when invoked with the `--ruby_out=`
+command-line flag. The parameter to the `--ruby_out=` option is the directory
+where you want the compiler to write your Ruby output. The compiler creates a
+`.rb` file for each `.proto` file input. The names of the output files are
+computed by taking the name of the `.proto` file and making two changes:
 
 -   The extension (`.proto`) is replaced with `_pb.rb`.
 -   The proto path (specified with the `--proto_path=` or `-I` command-line
@@ -70,7 +69,7 @@ Given a simple message declaration:
 message Foo {}
 ```
 
-The protocol buffer compiler generates a class called `Foo`. The generated class
+The Protobuf compiler generates a class called `Foo`. The generated class
 derives from the Ruby `Object` class (protos have no common base class). Unlike
 C++ and Java, Ruby generated code is unaffected by the `optimize_for` option in
 the `.proto` file; in effect, all Ruby code is optimized for code size.
@@ -96,8 +95,8 @@ The message classes also define the following methods as static. (In general we
 prefer static methods, since regular methods can conflict with field names you
 defined in your .proto file.)
 
--   `Message.decode(str)`: Decodes a binary protobuf for this message and
-    returns it in a new instance.
+-   `Message.decode(str)`: Decodes binary Protobuf data for this message type
+    and returns it in a new instance.
 -   `Message.encode(proto)`: Serializes a message object of this class to a
     binary string.
 -   `Message.decode_json(str)`: Decodes a JSON text string for this message and
@@ -159,11 +158,11 @@ range:
     assigning `1.0` to an int32 field is ok, but assigning `1.2` is not.
 -   **Boolean fields**: the value must be `true` or `false`. No other values
     will implicitly convert to true/false.
--   **Bytes fields**: the assigned value must be a `String` object. The protobuf
+-   **Bytes fields**: the assigned value must be a `String` object. The Protobuf
     library will duplicate the string, convert it to ASCII-8BIT encoding, and
     freeze it.
 -   **String fields**: the assigned value must be a `String` object. The
-    protobuf library will duplicate the string, convert it to UTF-8 encoding,
+    Protobuf library will duplicate the string, convert it to UTF-8 encoding,
     and freeze it.
 
 No automatic `#to_s`, `#to_i`, etc. calls will happen to perform automatic
diff --git a/content/reference/rust/_index.md b/content/reference/rust/_index.md
index 0520ea568..a0e926a07 100644
--- a/content/reference/rust/_index.md
+++ b/content/reference/rust/_index.md
@@ -2,6 +2,6 @@
 title = "Rust Reference"
 weight = 781
 linkTitle = "Rust"
-description = "Reference documentation for working with protocol buffer classes in Rust."
+description = "Reference documentation for working with Protobuf classes in Rust."
 type = "docs"
 +++
diff --git a/content/reference/rust/rust-design-decisions.md b/content/reference/rust/rust-design-decisions.md
index abb5f8ff3..8ee0da7f1 100644
--- a/content/reference/rust/rust-design-decisions.md
+++ b/content/reference/rust/rust-design-decisions.md
@@ -17,8 +17,8 @@ implementation makes and the considerations which led to those decisions.
 
 ## Designed to Be ‘Backed’ by Other Protobuf Implementations, Including C++ Protobuf {#backed-by-cpp}
 
-Protobuf Rust is not a pure Rust implementation of protobuf, but a safe Rust API
-implemented on top of existing protobuf implementations, or as we call these
+Protobuf Rust is not a pure Rust implementation of Protobuf, but a safe Rust API
+implemented on top of existing Protobuf implementations, or as we call these
 implementations: kernels.
 
 The biggest factor that goes into this decision was to enable zero-cost of
@@ -39,13 +39,13 @@ Rust adoption and require that these important cases stay on C++ instead.
 
 Protobuf Rust currently supports three kernels:
 
-*   C++ kernel - the generated code is backed by C++ Protocol Buffers (the
-    "full" implementation, typically used for servers). This kernel offers
-    in-memory interoperability with C++ code that uses the C++ runtime. This is
-    the default for servers within Google.
-*   C++ Lite kernel - the generated code is backed by C++ Lite Protocol Buffers
+*   C++ kernel - the generated code is backed by C++ Protobuf (the "full"
+    implementation, typically used for servers). This kernel offers in-memory
+    interoperability with C++ code that uses the C++ runtime. This is the
+    default for servers within Google.
+*   C++ Lite kernel - the generated code is backed by C++ Lite Protobuf
     (typically used for mobile). This kernel offers in-memory interoperability
-    with C++ code that uses the C++ Lite runtime. This is the default for
+    with C++ code that uses the C++ Lite runtime. This is the default
     for mobile apps within Google.
 *   upb kernel - the generated code is backed by
     [upb](https://github.com/protocolbuffers/protobuf/tree/main/upb),
diff --git a/content/reference/rust/rust-generated.md b/content/reference/rust/rust-generated.md
index 291e18699..000a5c992 100644
--- a/content/reference/rust/rust-generated.md
+++ b/content/reference/rust/rust-generated.md
@@ -2,16 +2,16 @@
 title = "Rust Generated Code Guide"
 weight = 782
 linkTitle = "Generated Code Guide"
-description = "Describes the API of message objects that the protocol buffer compiler generates for any given protocol definition."
+description = "Describes the API of message objects that the Protobuf compiler generates for any given protocol definition."
 type = "docs"
 +++
 
-This page describes exactly what Rust code the protocol buffer compiler
-generates for any given protocol definition.
+This page describes exactly what Rust code the Protobuf compiler generates for
+any given protocol definition.
 
-This document covers how the protocol buffer compiler generates Rust code for
-proto2, proto3, and protobuf editions. Any differences between proto2, proto3,
-and editions generated code are highlighted. You should read the
+This document covers how the Protobuf compiler generates Rust code for proto2,
+proto3, and Protobuf Editions. Any differences between proto2, proto3, and
+editions generated code are highlighted. You should read the
 [proto2 language guide](/programming-guides/proto2),
 [proto3 language guide](/programming-guides/proto3), or
 [editions guide](/programming-guides/editions) before
@@ -19,9 +19,8 @@ reading this document.
 
 ## Protobuf Rust {#rust}
 
-Protobuf Rust is an implementation of protocol buffers designed to be able to
-sit on top of other existing protocol buffer implementations that we refer to as
-'kernels'.
+Protobuf Rust is an implementation of Protobuf designed to be able to sit on top
+of other existing Protobuf implementations that we refer to as 'kernels'.
 
 The decision to support multiple non-Rust kernels has significantly influenced
 our public API, including the choice to use custom types like `ProtoStr` over
@@ -199,9 +198,9 @@ pub mod foo {
 
 ## Fields {#fields}
 
-In addition to the methods described in the previous section, the protocol
-buffer compiler generates a set of accessor methods for each field defined
-within the message in the `.proto` file.
+In addition to the methods described in the previous section, the Protobuf
+compiler generates a set of accessor methods for each field defined within the
+message in the `.proto` file.
 
 Following Rust style, the methods are in lower-case/snake-case, such as
 `has_foo()` and `clear_foo()`. Note that the capitalization of the field name
@@ -421,7 +420,7 @@ instead.
 
 `[ctype = CORD]` enables bytes and strings to be stored as an
 [absl::Cord](https://github.com/abseil/abseil-cpp/blob/master/absl/strings/cord.h)
-in C++ Protobufs. `absl::Cord` currently does not have an equivalent type in
+in C++ Protobuf. `absl::Cord` currently does not have an equivalent type in
 Rust . Protobuf Rust uses an enum to represent a cord
 field:
 
diff --git a/content/support/_index.md b/content/support/_index.md
index 1436c98d0..d81c8b16a 100644
--- a/content/support/_index.md
+++ b/content/support/_index.md
@@ -1,11 +1,11 @@
 +++
 title = "Support"
 weight = 900
-description = "Resources to support using Protocol Buffers."
+description = "Resources to support using Protobuf."
 type = "docs"
 +++
 
 This section of the documentation contains topics related to the support that
-the Protocol Buffers team provides to developers, including the timeframes for
-support for each version of a language library and migration guides to help you
-keep up with major version bumps.
+the Protobuf team provides to developers, including the timeframes for support
+for each version of a language library and migration guides to help you keep up
+with major version bumps.
diff --git a/content/support/debugging-playbook.md b/content/support/debugging-playbook.md
index 6f3883392..ebb92b196 100644
--- a/content/support/debugging-playbook.md
+++ b/content/support/debugging-playbook.md
@@ -1,11 +1,11 @@
 +++
 title = "Debugging"
 weight = 915
-description = "Debugging common issues in Protocol Buffers."
+description = "Debugging common issues in Protobuf."
 type = "docs"
 +++
 
-Frequently asked questions and debugging scenarios encountered by protobuf
+Frequently asked questions and debugging scenarios encountered by Protobuf
 users.
 
 
    
   
    
         Option
       The protocol buffer options.The Protobuf options.
     
    
     
    
       source_context