diff --git a/content/_index.md b/content/_index.md index 88133175..c80a6ccd 100644 --- a/content/_index.md +++ b/content/_index.md @@ -1,13 +1,11 @@ ---- -title: "Protocol Buffers" -weight: 5 -toc_hide: true -linkTitle: "Protocol Buffers" -no_list: "true" -type: docs -description: "Protocol Buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data." ---- - ++++ +title = "Protocol Buffers" +weight = 5 +toc_hide = "true" +description = "Protocol Buffers are language-neutral, platform-neutral extensible mechanisms for serializing structured data." +type = "docs" +no_list = "true" ++++ diff --git a/content/downloads.md b/content/downloads.md index 86317cce..757d7950 100644 --- a/content/downloads.md +++ b/content/downloads.md @@ -1,12 +1,9 @@ ---- -title: "Downloads" -weight: 1000 -toc_hide: false -linkTitle: "Downloads" -no_list: "true" -type: docs -description: "The downloads page for protocol buffers." ---- ++++ +title = "Downloads" +weight = 1000 +description = "The downloads page for protocol buffers." +type = "docs" ++++ ## Release Packages diff --git a/content/getting-started/_index.md b/content/getting-started/_index.md index 25b55199..9c349ca1 100644 --- a/content/getting-started/_index.md +++ b/content/getting-started/_index.md @@ -1,28 +1,12 @@ ---- -title: "Tutorials" -weight: 200 -toc_hide: false -linkTitle: "Tutorials" -no_list: "true" -type: docs -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." ---- - ++++ +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." +type = "docs" ++++ -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. The complete sample code for each application is also -provided. +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. - -* [C++](/getting-started/cpptutorial) -* [C#](/getting-started/csharptutorial) -* [Dart](/getting-started/darttutorial) -* [Go](/getting-started/gotutorial) -* [Java](/getting-started/javatutorial) -* [Kotlin](/getting-started/kotlintutorial) -* [Python](/getting-started/pythontutorial) diff --git a/content/getting-started/cpptutorial.md b/content/getting-started/cpptutorial.md index 50e6d0cf..9acc6e5d 100644 --- a/content/getting-started/cpptutorial.md +++ b/content/getting-started/cpptutorial.md @@ -1,13 +1,10 @@ ---- -title: "Protocol Buffer Basics: C++" -weight: 210 -toc_hide: false -linkTitle: "C++" -no_list: "true" -type: docs -description: "This tutorial provides a basic C++ programmers introduction to working with protocol buffers." ---- - ++++ +title = "Protocol Buffer Basics: C++" +weight = 210 +linkTitle = "C++" +description = "This tutorial provides a basic C++ programmers introduction to working with protocol buffers." +type = "docs" ++++ This tutorial provides a basic C++ programmers introduction to working with protocol buffers. By walking through creating a simple example application, it diff --git a/content/getting-started/csharptutorial.md b/content/getting-started/csharptutorial.md index d0c5db5f..4eacee2b 100644 --- a/content/getting-started/csharptutorial.md +++ b/content/getting-started/csharptutorial.md @@ -1,13 +1,10 @@ ---- -title: "Protocol Buffer Basics: C#" -weight: 220 -toc_hide: false -linkTitle: "C#" -no_list: "true" -type: docs -description: "This tutorial provides a basic C# programmers introduction to working with protocol buffers." ---- - ++++ +title = "Protocol Buffer Basics: C#" +weight = 220 +linkTitle = "C#" +description = "This tutorial provides a basic C# programmers introduction to working with protocol buffers." +type = "docs" ++++ This tutorial provides a basic C# programmer's introduction to working with protocol buffers, using the diff --git a/content/getting-started/darttutorial.md b/content/getting-started/darttutorial.md index 80b904ad..de751559 100644 --- a/content/getting-started/darttutorial.md +++ b/content/getting-started/darttutorial.md @@ -1,13 +1,10 @@ ---- -title: "Protocol Buffer Basics: Dart" -weight: 230 -toc_hide: false -linkTitle: "Dart" -no_list: "true" -type: docs -description: "This tutorial provides a basic Dart programmers introduction to working with protocol buffers." ---- - ++++ +title = "Protocol Buffer Basics: Dart" +weight = 230 +linkTitle = "Dart" +description = "This tutorial provides a basic Dart programmers introduction to working with protocol buffers." +type = "docs" ++++ This tutorial provides a basic Dart programmer's introduction to working with protocol buffers, using the diff --git a/content/getting-started/gotutorial.md b/content/getting-started/gotutorial.md index ae7d2759..9ff541a7 100644 --- a/content/getting-started/gotutorial.md +++ b/content/getting-started/gotutorial.md @@ -1,13 +1,10 @@ ---- -title: "Protocol Buffer Basics: Go" -weight: 240 -toc_hide: false -linkTitle: "Go" -no_list: "true" -type: docs -description: "This tutorial provides a basic Go programmers introduction to working with protocol buffers." ---- - ++++ +title = "Protocol Buffer Basics: Go" +weight = 240 +linkTitle = "Go" +description = "This tutorial provides a basic Go programmers introduction to working with protocol buffers." +type = "docs" ++++ This tutorial provides a basic Go programmer's introduction to working with protocol buffers, using the diff --git a/content/getting-started/javatutorial.md b/content/getting-started/javatutorial.md index 4959eef1..6e626240 100644 --- a/content/getting-started/javatutorial.md +++ b/content/getting-started/javatutorial.md @@ -1,13 +1,10 @@ ---- -title: "Protocol Buffer Basics: Java" -weight: 250 -toc_hide: false -linkTitle: "Java" -no_list: "true" -type: docs -description: "This tutorial provides a basic Java programmers introduction to working with protocol buffers." ---- - ++++ +title = "Protocol Buffer Basics: Java" +weight = 250 +linkTitle = "Java" +description = "This tutorial provides a basic Java programmers introduction to working with protocol buffers." +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 diff --git a/content/getting-started/kotlintutorial.md b/content/getting-started/kotlintutorial.md index 462a5562..0bdeb1c0 100644 --- a/content/getting-started/kotlintutorial.md +++ b/content/getting-started/kotlintutorial.md @@ -1,13 +1,10 @@ ---- -title: "Protocol Buffer Basics: Kotlin" -weight: 260 -toc_hide: false -linkTitle: "Kotlin" -no_list: "true" -type: docs -description: "This tutorial provides a basic Kotlin programmers introduction to working with protocol buffers." ---- - ++++ +title = "Protocol Buffer Basics: Kotlin" +weight = 260 +linkTitle = "Kotlin" +description = "This tutorial provides a basic Kotlin programmers introduction to working with protocol buffers." +type = "docs" ++++ This tutorial provides a basic Kotlin programmer's introduction to working with protocol buffers, using the diff --git a/content/getting-started/pythontutorial.md b/content/getting-started/pythontutorial.md index 5b73fd33..8ab8510b 100644 --- a/content/getting-started/pythontutorial.md +++ b/content/getting-started/pythontutorial.md @@ -1,13 +1,10 @@ ---- -title: "Protocol Buffer Basics: Python" -weight: 270 -toc_hide: false -linkTitle: "Python" -no_list: "true" -type: docs -description: "This tutorial provides a basic Python programmers introduction to working with protocol buffers." ---- - ++++ +title = "Protocol Buffer Basics: Python" +weight = 270 +linkTitle = "Python" +description = "This tutorial provides a basic Python programmers introduction to working with protocol buffers." +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 diff --git a/content/history.md b/content/history.md index a7c72578..a45ae45c 100644 --- a/content/history.md +++ b/content/history.md @@ -1,16 +1,13 @@ ---- -title: "History" -weight: 1020 -toc_hide: false -linkTitle: "History" -no_list: "true" -type: docs -description: "A brief history behind the creation of protocol buffers." ---- - -This is a brief history of protocol buffers. Understanding why it was created -and the decisions that changed it over time can help you to better utilize the -features of the tool. ++++ +title = "History" +weight = 1020 +description = "A brief history behind the creation of protocol buffers." +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. ## Why Did You Release Protocol Buffers? {#why} diff --git a/content/images/protobuf-editions-lifecycle-short.png b/content/images/protobuf-editions-lifecycle-short.png new file mode 100644 index 00000000..f3605509 Binary files /dev/null and b/content/images/protobuf-editions-lifecycle-short.png differ diff --git a/content/news/2022-05-06.md b/content/news/2022-05-06.md index b31e9a92..afc62b77 100644 --- a/content/news/2022-05-06.md +++ b/content/news/2022-05-06.md @@ -1,13 +1,11 @@ ---- -title: "Changes made on May 6, 2022" -weight: 26 -toc_hide: true -linkTitle: "May 6, 2022" -no_list: "true" -type: docs -description: "Changes made to Protocol Buffers on May 6, 2022." ---- - ++++ +title = "Changes announced May 6, 2022" +weight = 27 +linkTitle = "May 6, 2022" +toc_hide = "true" +description = "Changes announced for Protocol Buffers on May 6, 2022." +type = "docs" ++++ ## Versioning {#versioning} diff --git a/content/news/2022-07-06.md b/content/news/2022-07-06.md index 89f5bb1f..8a515d1d 100644 --- a/content/news/2022-07-06.md +++ b/content/news/2022-07-06.md @@ -1,13 +1,11 @@ ---- -title: "Changes announced July 6, 2022" -weight: 26 -toc_hide: true -linkTitle: "July 6, 2022" -no_list: "true" -type: docs -description: "Changes made to Protocol Buffers on July 6, 2022." ---- - ++++ +title = "Changes announced July 6, 2022" +weight = 26 +linkTitle = "July 6, 2022" +toc_hide = "true" +description = "Changes announced for Protocol Buffers on July 6, 2022." +type = "docs" ++++ ## Library Breaking Change Policy diff --git a/content/news/2022-08-03.md b/content/news/2022-08-03.md index f695da7f..f0fffeab 100644 --- a/content/news/2022-08-03.md +++ b/content/news/2022-08-03.md @@ -1,13 +1,11 @@ ---- -title: "Changes announced August 3, 2022" -weight: 24 -toc_hide: true -linkTitle: "August 3, 2022" -no_list: "true" -type: docs -description: "Changes made to Protocol Buffers on August 3, 2022." ---- - ++++ +title = "Changes announced August 3, 2022" +weight = 25 +linkTitle = "August 3, 2022" +toc_hide = "true" +description = "Changes announced for Protocol Buffers on August 3, 2022." +type = "docs" ++++ This topic covers two areas: general platform support changes, and C++-specific changes that are being considered for the 22.x release line. diff --git a/content/news/2023-04-11.md b/content/news/2023-04-11.md index 27f091a6..6335aa10 100644 --- a/content/news/2023-04-11.md +++ b/content/news/2023-04-11.md @@ -1,13 +1,11 @@ ---- -title: "Changes announced April 11, 2023" -weight: 23 -toc_hide: true -linkTitle: "April 11, 2023" -no_list: "true" -type: docs -description: "Changes announced for Protocol Buffers on April 11, 2023." ---- - ++++ +title = "Changes announced April 11, 2023" +weight = 24 +linkTitle = "April 11, 2023" +toc_hide = "true" +description = "Changes announced for Protocol Buffers on April 11, 2023." +type = "docs" ++++ ## Syntax Reflection Deprecation {#deprecation} diff --git a/content/news/2023-04-20.md b/content/news/2023-04-20.md index 30f57f0b..38c81951 100644 --- a/content/news/2023-04-20.md +++ b/content/news/2023-04-20.md @@ -1,13 +1,11 @@ ---- -title: "Changes announced April 20, 2023" -weight: 22 -toc_hide: true -linkTitle: "April 20, 2023" -no_list: "true" -type: docs -description: "Changes announced for Protocol Buffers on April 20, 2023." ---- - ++++ +title = "Changes announced April 20, 2023" +weight = 23 +linkTitle = "April 20, 2023" +toc_hide = "true" +description = "Changes announced for Protocol Buffers on April 20, 2023." +type = "docs" ++++ ## Changes to Ruby Generator {#ruby} diff --git a/content/news/2023-04-28.md b/content/news/2023-04-28.md index 0c7fe257..d53304fb 100644 --- a/content/news/2023-04-28.md +++ b/content/news/2023-04-28.md @@ -1,13 +1,11 @@ ---- -title: "Changes announced April 28, 2023" -weight: 21 -toc_hide: true -linkTitle: "April 28, 2023" -no_list: "true" -type: docs -description: "Changes announced for Protocol Buffers on April 28, 2023." ---- - ++++ +title = "Changes announced April 28, 2023" +weight = 22 +linkTitle = "April 28, 2023" +toc_hide = "true" +description = "Changes announced for Protocol Buffers on April 28, 2023." +type = "docs" ++++ ## Stricter validation for `json_name` {#json-name} diff --git a/content/news/_index.md b/content/news/_index.md index 41634605..cb09451a 100644 --- a/content/news/_index.md +++ b/content/news/_index.md @@ -1,12 +1,9 @@ ---- -title: "News" -weight: 20 -toc_hide: false -linkTitle: "News" -no_list: "true" -type: docs -description: "Get the latest news about Protocol Buffers." ---- ++++ +title = "News" +weight = 20 +description = "Get the latest news about Protocol Buffers." +type = "docs" ++++ News topics provide information about past events and changes with Protocol Buffers, and plans for upcoming changes. diff --git a/content/overview.md b/content/overview.md index 76cea453..8c2af80f 100644 --- a/content/overview.md +++ b/content/overview.md @@ -1,20 +1,15 @@ ---- -title: "Overview" -weight: 10 -toc_hide: false -linkTitle: "Overview" -no_list: "true" -type: docs -description: "Protocol Buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data." ---- - -Protocol buffers provide a language-neutral, platform-neutral, extensible -mechanism for serializing structured data in a forward-compatible and -backward-compatible way. 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. ++++ +title = "Overview" +weight = 10 +description = "Protocol Buffers are 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. Protocol buffers are a combination of the definition language (created in `.proto` files), the code that the proto compiler generates to interface with diff --git a/content/programming-guides/_index.md b/content/programming-guides/_index.md index 6766e6f0..38f09fd4 100644 --- a/content/programming-guides/_index.md +++ b/content/programming-guides/_index.md @@ -1,17 +1,6 @@ ---- -title: "Programming Guides" -weight: 27 -toc_hide: false -linkTitle: "Programming Guides" -no_list: "true" -type: docs -description: "Learn how to use Protocol Buffers in your projects." ---- - - -* [Language Guide (proto2)](/programming-guides/proto) -* [Language Guide (proto3)](/programming-guides/proto3) -* [Style Guide](/programming-guides/style) -* [Encoding](/programming-guides/encoding) -* [Techniques](/programming-guides/techniques) -* [Add-ons](/programming-guides/addons) ++++ +title = "Programming Guides" +weight = 27 +description = "Learn how to use Protocol Buffers in your projects." +type = "docs" ++++ diff --git a/content/programming-guides/addons.md b/content/programming-guides/addons.md index 7e1eba87..ff7013ad 100644 --- a/content/programming-guides/addons.md +++ b/content/programming-guides/addons.md @@ -1,12 +1,10 @@ ---- -title: "Third-party Add-ons" -weight: 80 -toc_hide: false -linkTitle: "Add-ons" -no_list: "true" -type: docs -description: "This topic links out to many open source projects that seek to add useful functionality on top of Protocol Buffers." ---- ++++ +title = "Third-Party Add-ons" +weight = 80 +linkTitle = "Add-ons" +description = "This topic links out to many open source projects that seek to add useful functionality on top of Protocol Buffers." +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 diff --git a/content/programming-guides/api.md b/content/programming-guides/api.md index 39707379..2b45040e 100644 --- a/content/programming-guides/api.md +++ b/content/programming-guides/api.md @@ -1,17 +1,13 @@ ---- -title: "API Best Practices" -weight: 100 -toc_hide: false -linkTitle: "API Best Practices" -no_list: "true" -type: docs -description: "A future-proof API is surprisingly hard to get right. The suggestions in this document make trade-offs to favor long-term, bug-free evolution." ---- ++++ +title = "API Best Practices" +weight = 100 +description = "A future-proof API is surprisingly hard to get right. The suggestions in this document make trade-offs to favor long-term, bug-free evolution." +type = "docs" ++++ Updated for proto3. Patches welcome! -The suggestions in this document make trade-offs to favor -long-term, bug-free evolution. This doc is a complement to +This doc is a complement to [Proto Best Practices](/programming-guides/dos-donts). It's not a prescription for Java/C++/Go and other APIs. diff --git a/content/programming-guides/dos-donts.md b/content/programming-guides/dos-donts.md index 327e8376..8a2e7f35 100644 --- a/content/programming-guides/dos-donts.md +++ b/content/programming-guides/dos-donts.md @@ -1,12 +1,9 @@ ---- -title: "Proto Best Practices" -weight: 90 -toc_hide: false -linkTitle: "Proto Best Practices" -no_list: "true" -type: docs -description: "This topic contains vetted best practices for authoring Protocol Buffers." ---- ++++ +title = "Proto Best Practices" +weight = 90 +description = "This topic contains vetted best practices for authoring Protocol Buffers." +type = "docs" ++++ Clients and servers are never updated at exactly the same time - even when you try to update them at the same time. One or the diff --git a/content/programming-guides/encoding.md b/content/programming-guides/encoding.md index eb838c33..e7fa3bcd 100644 --- a/content/programming-guides/encoding.md +++ b/content/programming-guides/encoding.md @@ -1,12 +1,9 @@ ---- -title: "Encoding" -weight: 60 -toc_hide: false -linkTitle: "Encoding" -no_list: "true" -type: docs -description: "This topic explains how Protocol Buffers encodes data to files or to the wire." ---- ++++ +title = "Encoding" +weight = 60 +description = "This topic explains how Protocol Buffers 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 @@ -221,7 +218,7 @@ For example, `-500z` is the same as the varint `999`. Non-varint numeric types are simple -- `double` and `fixed64` have wire type `I64`, which tells the parser to expect a fixed eight-byte lump of data. We can specify a `double` record by writing `5: 25.4`, or a `fixed64` record with `6: -200i64`. In both cases, omitting an explicit wire type infers the `I64` wire +200i64`. In both cases, omitting an explicit wire type implies the `I64` wire type. Similarly `float` and `fixed32` have wire type `I32`, which tells it to expect @@ -253,7 +250,7 @@ up the bytes, ``` we see that the tag, `` `12` ``, is `00010 010`, or `2:LEN`. The byte that -follows is the signed int32 varint `7`, and the next seven bytes are the UTF-8 +follows is the int32 varint `7`, and the next seven bytes are the UTF-8 encoding of `"testing"`. The int32 varint means that the max length of a string is 2GB. @@ -366,9 +363,8 @@ concatenation) even if you do not know their types. Starting in v2.1.0, `repeated` fields of [scalar type](/programming-guides/proto2#scalar) can be -declared as "packed". In proto2 this is done with using the field option -`[packed=true]`, but in proto3 it is the default. Repeated enums may be packable -at some point, but they currently are not. +declared as "packed". In proto2 this is done using the field option +`[packed=true]`. In proto3 it is the default. Instead of being encoded as one record per entry, they are encoded as a single `LEN` record that contains each element concatenated. To decode, elements are diff --git a/content/programming-guides/enum.md b/content/programming-guides/enum.md index d11f79d8..7d5f6a93 100644 --- a/content/programming-guides/enum.md +++ b/content/programming-guides/enum.md @@ -1,12 +1,9 @@ ---- -title: "Enum Behavior" -weight: 55 -toc_hide: false -linkTitle: "Enum Behavior" -no_list: "true" -type: docs -description: "This topic explains how enums currently work in Protocol Buffers vs. how they should work." ---- ++++ +title = "Enum Behavior" +weight = 55 +description = "This topic explains how enums currently work in Protocol Buffers 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 @@ -191,3 +188,7 @@ enum. ### Swift {#swift} Swift is conformant. + +### Dart {#dart} + +Dart treats all enums as **closed**. diff --git a/content/programming-guides/field_presence.md b/content/programming-guides/field_presence.md index b2d1d4f3..fe237d55 100644 --- a/content/programming-guides/field_presence.md +++ b/content/programming-guides/field_presence.md @@ -1,16 +1,10 @@ ---- -title: "Application Note: Field Presence" -weight: 85 -toc_hide: false -linkTitle: "Field Presence" -no_list: "true" -type: docs -description: "This topic 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." ---- - -This application note explains the various presence tracking disciplines for -protobuf fields. It also explains the behaviour of explicit presence tracking -for singular proto3 fields with basic types. ++++ +title = "Application Note: Field Presence" +weight = 85 +linkTitle = "Field Presence" +description = "This topic 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 diff --git a/content/programming-guides/proto2.md b/content/programming-guides/proto2.md index 7f969c0f..26eabb26 100644 --- a/content/programming-guides/proto2.md +++ b/content/programming-guides/proto2.md @@ -1,14 +1,10 @@ ---- -title: "Language Guide (proto 2)" -weight: 30 -toc_hide: false -linkTitle: "Language Guide (proto 2)" -no_list: "true" -type: docs -description: "This topic covers how to use the version 2 of Protocol Buffers in your project. It contains language-agnostic content. For information specific to the language you're using, see the corresponding documentation for your language." -aliases: - - /programming-guides/proto/ ---- ++++ +title = "Language Guide (proto 2)" +weight = 30 +description = "This topic covers how to use the version 2 of Protocol Buffers 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 @@ -1667,9 +1663,9 @@ options using extensions. The following example shows the syntax for adding these options: ```proto -import "net/proto2/proto/descriptor.proto"; +import "google/protobuf/descriptor.proto"; -extend proto2.EnumValueOptions { +extend google.protobuf.EnumValueOptions { optional string string_name = 123456789; } diff --git a/content/programming-guides/proto3.md b/content/programming-guides/proto3.md index 77d943ed..2430a103 100644 --- a/content/programming-guides/proto3.md +++ b/content/programming-guides/proto3.md @@ -1,12 +1,9 @@ ---- -title: "Language Guide (proto 3)" -weight: 40 -toc_hide: false -linkTitle: "Language Guide (proto 3)" -no_list: "true" -type: docs -description: "This topic covers how to use the version 3 of Protocol Buffers in your project. It contains language-agnostic content. For information specific to the language you're using, see the corresponding documentation for your language." ---- ++++ +title = "Language Guide (proto 3)" +weight = 40 +description = "This topic covers how to use the version 3 of Protocol Buffers 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 diff --git a/content/programming-guides/style.md b/content/programming-guides/style.md index 721ed37b..ebcddd41 100644 --- a/content/programming-guides/style.md +++ b/content/programming-guides/style.md @@ -1,12 +1,9 @@ ---- -title: "Style Guide" -weight: 50 -toc_hide: false -linkTitle: "Style Guide" -no_list: "true" -type: docs -description: "This topic provides direction for how best to stucture your proto definitions." ---- ++++ +title = "Style Guide" +weight = 50 +description = "This topic provides direction for how best to structure your proto definitions." +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 @@ -57,7 +54,7 @@ message SongServerRequest { ``` Using this naming convention for field names gives you accessors like those -shown in the the following two code samples. +shown in the following two code samples. C++: diff --git a/content/programming-guides/techniques.md b/content/programming-guides/techniques.md index 9e287d5a..c6f63e4d 100644 --- a/content/programming-guides/techniques.md +++ b/content/programming-guides/techniques.md @@ -1,15 +1,12 @@ ---- -title: "Techniques" -weight: 70 -toc_hide: false -linkTitle: "Techniques" -no_list: "true" -type: docs -description: "This topic describes some commonly-used design patterns for dealing with Protocol Buffers." ---- - -This page describes some commonly-used design patterns for dealing with Protocol -Buffers. You can also send design and usage questions to the ++++ +title = "Techniques" +weight = 70 +description = "This topic describes some commonly-used design patterns for dealing with Protocol Buffers." +type = "docs" ++++ + +You can also send design and usage questions to +the [Protocol Buffers discussion group](http://groups.google.com/group/protobuf). ## Streaming Multiple Messages {#streaming} diff --git a/content/reference/_index.md b/content/reference/_index.md index 99f54b1b..77d783ed 100644 --- a/content/reference/_index.md +++ b/content/reference/_index.md @@ -1,13 +1,9 @@ ---- -title: "Reference Guides" -weight: 490 -toc_hide: false -linkTitle: "Reference Guides" -no_list: "true" -type: docs -description: "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." ---- - ++++ +title = "Reference Guides" +weight = 490 +description = "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." +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 @@ -20,66 +16,3 @@ for each language includes (where available): Note that there are APIs for several more languages in the pipeline -- for details, see [Other Languages](/reference/other). - -### C++ Reference - -- [C++ Generated Code Guide](/reference/cpp/cpp-generated) -- [C++ Arena Allocation Guide](/reference/cpp/arenas) - -- [C++ API](/reference/cpp/api-docs/) - -### C\# Reference - -- [C\# Generated Code Guide](/reference/csharp/csharp-generated) -- [C\# API](/reference/csharp/api-docs/) - -### Dart Reference - -- [Dart Generated Code Guide](/reference/dart/dart-generated) -- [Dart API (Dartdoc)](//pub.dartlang.org/documentation/protobuf) - -### Go Reference - -- [Go Generated Code Guide](/reference/go/go-generated) -- [Go API (godoc)](https://pkg.go.dev/google.golang.org/protobuf/proto) - -- [Go FAQ](/reference/go/faq) - -### Java Reference - -- [Java Generated Code Guide](/reference/java/java-generated) -- [Java Proto Names](/reference/java/java-proto-names) -- [Java API (Javadoc)](/reference/java/api-docs/overview-summary.html) - -### Kotlin Reference - -- [Kotlin Generated Code Guide](/reference/kotlin/kotlin-generated) -- [Kotlin API](/reference/kotlin/api-docs) - -### Objective-C Reference - -- [Objective-C Generated Code Guide](/reference/objective-c/objective-c-generated) - -### PHP Reference - -- [PHP Generated Code Guide](/reference/php/php-generated) -- [PHP API](/reference/php/api-docs) - -### Python Reference - -- [Python Generated Code Guide](/reference/python/python-generated) -- [Python API (Sphinx)](https://googleapis.dev/python/protobuf/latest/) - -### Ruby Reference - -- [Ruby Generated Code Guide](/reference/ruby/ruby-generated) - -### Protocol Buffers Reference - -- [Protocol Buffers Version 2 Language Specification](/reference/protobuf/proto2-spec) -- [Protocol Buffers Version 3 Language Specification](/reference/protobuf/proto3-spec) -- [Text Format Language Specification](/reference/protobuf/textformat-spec) - -### Other - -- [Other Languages](/reference/other) diff --git a/content/reference/cpp/_index.md b/content/reference/cpp/_index.md index 988dd016..89410f9e 100644 --- a/content/reference/cpp/_index.md +++ b/content/reference/cpp/_index.md @@ -1,15 +1,7 @@ ---- -title: "C++ Reference" -weight: 500 -toc_hide: false -linkTitle: "C++ Reference" -no_list: "true" -type: docs -description: "This section contains reference documentation for working with protocol buffer classes in C++." ---- - - -* [C++ Generated Code Guide](/reference/cpp/cpp-generated) -* [C++ Arena Allocation Guide](/reference/cpp/arenas) - -* [C++ API](/reference/cpp/api-docs) ++++ +title = "C++ Reference" +weight = 500 +linkTitle = "C++" +description = "This section contains reference documentation for working with protocol buffer classes in C++." +type = "docs" ++++ diff --git a/content/reference/cpp/arenas.md b/content/reference/cpp/arenas.md index 5a951752..550fb924 100644 --- a/content/reference/cpp/arenas.md +++ b/content/reference/cpp/arenas.md @@ -1,17 +1,13 @@ ---- -title: "C++ Arena Allocation Guide" -weight: 520 -toc_hide: false -linkTitle: "Arena Allocation Guide" -no_list: "true" -type: docs -description: "Arena allocation is a C++-only feature that helps you optimize your memory usage and improve performance when working with protocol buffers." ---- - -Arena allocation is a C++-only feature that helps you optimize your memory usage -and improve performance when working with protocol buffers. This page describes -exactly what C++ code the protocol buffer compiler generates in addition to the -code described in the ++++ +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." +type = "docs" ++++ + +This page describes exactly what C++ code the protocol +buffer 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 diff --git a/content/reference/cpp/cpp-generated.md b/content/reference/cpp/cpp-generated.md index 74ca352c..193d6cb0 100644 --- a/content/reference/cpp/cpp-generated.md +++ b/content/reference/cpp/cpp-generated.md @@ -1,18 +1,15 @@ ---- -title: "C++ Generated Code Guide" -weight: 510 -toc_hide: false -linkTitle: "Generated Code Guide" -no_list: "true" -type: docs -description: "This topic describes exactly what C++ code the protocol buffer compiler generates for any given protocol definition. " ---- - -This page describes exactly what C++ code the protocol buffer compiler generates -for any given protocol definition. 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 message -classes/interfaces, which are the same in both versions. You should read the ++++ +title = "C++ Generated Code Guide" +weight = 510 +linkTitle = "Generated Code Guide" +description = "This topic describes exactly what C++ code the protocol buffer 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 message classes/interfaces, which are the same in both versions. +You should read the [proto2 language guide](/programming-guides/proto) and/or [proto3 language guide](/programming-guides/proto3) before reading this document. @@ -854,6 +851,7 @@ class Map { T& at(const Key& key); // Lookup + bool contains(const Key& key) const; int count(const Key& key) const; const_iterator find(const Key& key) const; iterator find(const Key& key); diff --git a/content/reference/csharp/_index.md b/content/reference/csharp/_index.md index a2a4f156..4a410c5f 100644 --- a/content/reference/csharp/_index.md +++ b/content/reference/csharp/_index.md @@ -1,13 +1,7 @@ ---- -title: "C# Reference" -weight: 540 -toc_hide: false -linkTitle: "C#" -no_list: "true" -type: docs -description: "This section contains reference documentation for working with protocol buffer classes in C#" ---- - - -* [C# Generated Code Guide](/reference/csharp/csharp-generated) -* [C# API](/reference/csharp/api-docs/) ++++ +title = "C# Reference" +weight = 540 +linkTitle = "C#" +description = "This section contains reference documentation for working with protocol buffer classes in C#" +type = "docs" ++++ diff --git a/content/reference/csharp/csharp-generated.md b/content/reference/csharp/csharp-generated.md index 0471769e..73ff6c27 100644 --- a/content/reference/csharp/csharp-generated.md +++ b/content/reference/csharp/csharp-generated.md @@ -1,15 +1,13 @@ ---- -title: "C# Generated Code Guide" -weight: 550 -toc_hide: false -linkTitle: "Generated Code Guide" -no_list: "true" -type: docs -description: "This topic describes exactly what C# code the protocol buffer compiler generates for protocol definitions using proto3 syntax." ---- - -This page describes exactly what C\# code the protocol buffer compiler generates -for protocol definitions using `proto3` syntax. You should read the ++++ +title = "C# Generated Code Guide" +weight = 550 +linkTitle = "Generated Code Guide" +description = "This topic describes exactly what C# code the protocol buffer compiler generates for protocol definitions using proto3 syntax." +type = "docs" ++++ + +You should +read the [proto3 language guide](/programming-guides/proto3) before reading this document. diff --git a/content/reference/dart/_index.md b/content/reference/dart/_index.md index 6a30dc3e..d48ab5f5 100644 --- a/content/reference/dart/_index.md +++ b/content/reference/dart/_index.md @@ -1,13 +1,7 @@ ---- -title: "Dart Reference" -weight: 570 -toc_hide: false -linkTitle: "Dart" -no_list: "true" -type: docs -description: "This section contains reference documentation for working with protocol buffer classes in Dart" ---- - - -* [Dart Generated Code Guide](/reference/dart/dart-generated) -* [Dart API](https://pub.dev/documentation/protobuf/latest/) ++++ +title = "Dart Reference" +weight = 570 +linkTitle = "Dart" +description = "This section contains reference documentation for working with protocol buffer classes in Dart" +type = "docs" ++++ diff --git a/content/reference/dart/dart-generated.md b/content/reference/dart/dart-generated.md index baf3cccd..e1610046 100644 --- a/content/reference/dart/dart-generated.md +++ b/content/reference/dart/dart-generated.md @@ -1,18 +1,15 @@ ---- -title: "Dart Generated Code Guide" -weight: 580 -toc_hide: false -linkTitle: "Generated Code Guide" -no_list: "true" -type: docs -description: "This topic describes what Dart code the protocol buffer compiler generates for any given protocol definition." ---- - -This page describes what Dart code the protocol buffer compiler generates for -any given protocol definition. 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 ++++ +title = "Dart Generated Code" +weight = 580 +linkTitle = "Generated Code" +description = "This topic describes what Dart code the protocol buffer 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 [proto2 language guide](/programming-guides/proto) and/or the [proto3 language guide](/programming-guides/proto3) before reading this document. @@ -153,6 +150,15 @@ The compiler will generate the following accessor methods in the message class: - `void clearFoo()`: Clears the value of the field. After calling this,`get foo` will return the default value. +**NOTE:** Due to a quirk in the Dart proto3 implementation, the following +methods are generated even if the `optional` modifier, used to request +[presence semantics](/programming-guides/field_presence#presence-in-proto3-apis), +isn't in the proto definition. + +- `bool hasFoo()`: Returns `true` if the field is set. +- `void clearFoo()`: Clears the value of the field. After calling this, + `hasFoo()` will return `false` and `get foo` will return the default value. + ### Singular Message Fields {#singular-message} Given the message type: diff --git a/content/reference/go/_index.md b/content/reference/go/_index.md index 8e0d111b..625787a3 100644 --- a/content/reference/go/_index.md +++ b/content/reference/go/_index.md @@ -1,15 +1,7 @@ ---- -title: "Go Reference" -weight: 600 -toc_hide: false -linkTitle: "Go" -no_list: "true" -type: docs -description: "This section contains reference documentation for working with protocol buffer classes in Go" ---- - - -* [Go Generated Code Guide](/reference/go/go-generated) -* [Go API (godoc)](https://pkg.go.dev/google.golang.org/protobuf/proto) - -* [Go FAQ](/reference/go/faq) ++++ +title = "Go Reference" +weight = 600 +linkTitle = "Go" +description = "This section contains reference documentation for working with protocol buffer classes in Go" +type = "docs" ++++ diff --git a/content/reference/go/faq.md b/content/reference/go/faq.md index a990aa5b..374811e7 100644 --- a/content/reference/go/faq.md +++ b/content/reference/go/faq.md @@ -1,12 +1,10 @@ ---- -title: "Go FAQ" -weight: 620 -toc_hide: false -linkTitle: "FAQ" -no_list: "true" -type: docs -description: "This topic has a list of frequently asked questions about implementing protocol buffers in Go, with answer for each." ---- ++++ +title = "Go FAQ" +weight = 620 +linkTitle = "FAQ" +description = "This topic has a list of frequently asked questions about implementing protocol buffers in Go, with answer for each." +type = "docs" ++++ ## Versions diff --git a/content/reference/go/go-generated.md b/content/reference/go/go-generated.md index f690eaad..c2c9db4c 100644 --- a/content/reference/go/go-generated.md +++ b/content/reference/go/go-generated.md @@ -1,18 +1,15 @@ ---- -title: "Go Generated Code Guide" -weight: 610 -toc_hide: false -linkTitle: "Generated Code Guide" -no_list: "true" -type: docs -description: "This topic describes exactly what Go code the protocol buffer compiler generates for any given protocol definition." ---- - -This page describes exactly what Go code the protocol buffer compiler generates -for any given protocol definition. 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 ++++ +title = "Go Generated Code Guide" +weight = 610 +linkTitle = "Generated Code Guide" +description = "This topic describes exactly what Go code the protocol buffer 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 [proto2 language guide](/programming-guides/proto) and/or the [proto3 language guide](/programming-guides/proto3) before reading this document. diff --git a/content/reference/java/_index.md b/content/reference/java/_index.md index 23d95dd0..3fe24172 100644 --- a/content/reference/java/_index.md +++ b/content/reference/java/_index.md @@ -1,14 +1,7 @@ ---- -title: "Java Reference" -weight: 640 -toc_hide: false -linkTitle: "Java" -no_list: "true" -type: docs -description: "This section contains reference documentation for working with protocol buffer classes in Java" ---- - - -* [Java Generated Code Guide](/reference/java/java-generated) -* [Java Proto Names](/reference/java/java-proto-names) -* [Java API (Javadoc)](/reference/java/api-docs/overview-summary.html) ++++ +title = "Java Reference" +weight = 640 +linkTitle = "Java" +description = "This section contains reference documentation for working with protocol buffer classes in Java." +type = "docs" ++++ diff --git a/content/reference/java/java-generated.md b/content/reference/java/java-generated.md index f3f78c24..07cc634d 100644 --- a/content/reference/java/java-generated.md +++ b/content/reference/java/java-generated.md @@ -1,18 +1,16 @@ ---- -title: "Java Generated Code Guide" -weight: 650 -toc_hide: false -linkTitle: "Generated Code Guide" -no_list: "true" -type: docs -description: "This topic describes exactly what Java code the protocol buffer compiler generates for any given protocol definition." ---- - -This page describes exactly what Java code the protocol buffer compiler -generates for any given protocol definition. 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 message -classes/interfaces, which are the same in both versions. You should read the ++++ +title = "Java Generated Code Guide" +weight = 650 +linkTitle = "Generated Code Guide" +description = "This topic describes exactly what Java code the protocol buffer 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 message classes/interfaces, which are the same in both versions. +You should read the [proto2 language guide](/programming-guides/proto) and/or [proto3 language guide](/programming-guides/proto3) before reading this document. diff --git a/content/reference/java/java-proto-names.md b/content/reference/java/java-proto-names.md index 87ac351e..a424f45a 100644 --- a/content/reference/java/java-proto-names.md +++ b/content/reference/java/java-proto-names.md @@ -1,12 +1,10 @@ ---- -title: "Java Proto Names" -weight: 655 -toc_hide: false -linkTitle: "Generated Proto Names" -no_list: "true" -type: docs -description: "This topic covers the names that are generated by the immutable API." ---- ++++ +title = "Java Proto Names" +weight = 655 +linkTitle = "Generated Proto Names" +description = "This topic covers the names that are generated by the immutable API." +type = "docs" ++++ This document contains information on what the fully-qualified Java name of a proto is, based on the different proto options. This name corresponds to the diff --git a/content/reference/kotlin/_index.md b/content/reference/kotlin/_index.md index 0935f7ef..fe24a7fc 100644 --- a/content/reference/kotlin/_index.md +++ b/content/reference/kotlin/_index.md @@ -1,13 +1,7 @@ ---- -title: "Kotlin Reference" -weight: 670 -toc_hide: false -linkTitle: "Kotlin" -no_list: "true" -type: docs -description: "This section contains reference documentation for working with protocol buffer classes in Kotlin" ---- - - -* [Kotlin Generated Code Guide](/reference/kotlin/kotlin-generated) -* [Kotlin API](/reference/kotlin/api-docs) ++++ +title = "Kotlin Reference" +weight = 670 +linkTitle = "Kotlin" +description = "This section contains reference documentation for working with protocol buffer classes in Kotlin." +type = "docs" ++++ diff --git a/content/reference/kotlin/api-docs/_index.md b/content/reference/kotlin/api-docs/_index.md index 310be106..a773cb70 100644 --- a/content/reference/kotlin/api-docs/_index.md +++ b/content/reference/kotlin/api-docs/_index.md @@ -1,15 +1,10 @@ ---- -title: "Kotlin API" -weight: 690 -toc_hide: false -linkTitle: "Kotlin API" -no_list: "true" -type: docs -description: "The API docs for Kotlin." ---- - - -//[protobuf-kotlin](./) ++++ +title = "Kotlin Reference" +weight = 670 +linkTitle = "Kotlin" +description = "This section contains reference documentation for working with protocol buffers in Kotlin." +type = "docs" ++++ ## Packages diff --git a/content/reference/kotlin/kotlin-generated.md b/content/reference/kotlin/kotlin-generated.md index ba8f9c93..426cd17c 100644 --- a/content/reference/kotlin/kotlin-generated.md +++ b/content/reference/kotlin/kotlin-generated.md @@ -1,20 +1,15 @@ ---- -title: "Kotlin Generated Code Guide" -weight: 680 -toc_hide: false -linkTitle: "Generated Code Guide" -no_list: "true" -type: docs -description: "This topic describes exactly what Kotlin code the protocol buffer compiler generates for any given protocol definition," ---- - -This page describes exactly what Kotlin code the protocol buffer compiler -generates for any given protocol definition, in addition to the code generated -for [Java](/reference/java/java-generated). 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 message classes/interfaces, which are the same in both versions. -You should read the ++++ +title = "Kotlin Generated Code Guide" +weight = 680 +linkTitle = "Generated Code Guide" +description = "This topic describes exactly what Kotlin code the protocol buffer compiler generates for any given protocol definition, in addition to the code generated for Java." +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 message classes/interfaces, which are +the same in both versions. You should read the [proto2 language guide](/programming-guides/proto) and/or [proto3 language guide](/programming-guides/proto3) before reading this document. diff --git a/content/reference/objective-c/_index.md b/content/reference/objective-c/_index.md index 648ee237..a832281b 100644 --- a/content/reference/objective-c/_index.md +++ b/content/reference/objective-c/_index.md @@ -1,12 +1,7 @@ ---- -title: "Objective-C Reference" -weight: 700 -toc_hide: false -linkTitle: "Objective-C" -no_list: "true" -type: docs -description: "This section contains reference documentation for working with protocol buffer classes in Objective-C" ---- - - -* [Objective-C Generated Code Guide](/reference/objective-c/objective-c-generated) ++++ +title = "Objective-C Reference" +weight = 700 +linkTitle = "Objective-C" +description = "This section contains reference documentation for working with protocol buffer 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 45965602..4f4243b6 100644 --- a/content/reference/objective-c/objective-c-generated.md +++ b/content/reference/objective-c/objective-c-generated.md @@ -1,16 +1,14 @@ ---- -title: "Objective-C Generated Code Guide" -weight: 710 -toc_hide: false -linkTitle: "Generated Code Guide" -no_list: "true" -type: docs -description: "This topic describes exactly what Objective-C code the protocol buffer compiler generates for any given protocol definition." ---- - -This page describes exactly what Objective-C code the protocol buffer compiler -generates for any given protocol definition. Any differences between proto2 and -proto3 generated code are highlighted. You should read the ++++ +title = "Objective-C Generated Code Guide" +weight = 710 +linkTitle = "Generated Code Guide" +description = "This topic describes exactly what Objective-C code the protocol buffer compiler generates for any given protocol definition." +type = "docs" ++++ + +Any +differences between proto2 and proto3 generated code are highlighted. You should +read the [proto2 language guide](/programming-guides/proto) and/or [proto3 language guide](/programming-guides/proto3) before reading this document. diff --git a/content/reference/other.md b/content/reference/other.md index aaa5bcbc..8eb69e5d 100644 --- a/content/reference/other.md +++ b/content/reference/other.md @@ -1,12 +1,9 @@ ---- -title: "Other Languages" -weight: 840 -toc_hide: false -linkTitle: "Other Languages" -no_list: "true" -type: docs -description: "protoc, the Protocol Buffers Compiler, can be extended to support new languages via plugins." ---- ++++ +title = "Other Languages" +weight = 840 +description = "protoc, the Protocol Buffers 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 diff --git a/content/reference/php/_index.md b/content/reference/php/_index.md index e5c4ab7f..0511c24c 100644 --- a/content/reference/php/_index.md +++ b/content/reference/php/_index.md @@ -1,13 +1,7 @@ ---- -title: "PHP Reference" -weight: 720 -toc_hide: false -linkTitle: "PHP" -no_list: "true" -type: docs -description: "This section contains reference documentation for working with protocol buffer classes in PHP" ---- - - -* [PHP Generated Code Guide](/reference/php/php-generated) -* [PHP API](/reference/php/api-docs) ++++ +title = "PHP Reference" +weight = 720 +linkTitle = "PHP" +description = "This section contains reference documentation for working with protocol buffer classes in PHP." +type = "docs" ++++ diff --git a/content/reference/php/php-generated.md b/content/reference/php/php-generated.md index ef276d55..df11614b 100644 --- a/content/reference/php/php-generated.md +++ b/content/reference/php/php-generated.md @@ -1,15 +1,12 @@ ---- -title: "PHP Generated Code Guide" -weight: 730 -toc_hide: false -linkTitle: "Generated Code Guide" -no_list: "true" -type: docs -description: "This topic describes the PHP code that the protocol buffer compiler generates for any given protocol definition." ---- - -This page describes the PHP code that the protocol buffer compiler generates for -any given protocol definition. You should read the ++++ +title = "PHP Generated Code Guide" +weight = 730 +linkTitle = "Generated Code Guide" +description = "This topic describes the PHP code that the protocol buffer compiler generates for any given protocol definition." +type = "docs" ++++ + +You should read the [proto3 language guide](/programming-guides/proto3) before reading this document. Note that the protocol buffer compiler currently only supports proto3 code generation for PHP. diff --git a/content/reference/protobuf/_index.md b/content/reference/protobuf/_index.md index 70f39305..5aa38f92 100644 --- a/content/reference/protobuf/_index.md +++ b/content/reference/protobuf/_index.md @@ -1,14 +1,7 @@ ---- -title: "Protocol Buffers Reference" -weight: 790 -toc_hide: false -linkTitle: "Protocol Buffers" -no_list: "true" -type: docs -description: "This section contains language-agnostic information about how to use protocol buffers." ---- - - -* [Protocol Buffers Version 2 Language Specification](/reference/protobuf/proto2-spec) -* [Protocol Buffers Version 3 Language Specification](/reference/protobuf/proto3-spec) -* [Text Format Language Specification](/reference/protobuf/textformat-spec) ++++ +title = "Protocol Buffers Reference" +weight = 790 +linkTitle = "Protocol Buffers" +description = "This section contains language-agnostic information about how to use protocol buffers." +type = "docs" ++++ diff --git a/content/reference/protobuf/google.protobuf.md b/content/reference/protobuf/google.protobuf.md index bfca678c..670d2b47 100644 --- a/content/reference/protobuf/google.protobuf.md +++ b/content/reference/protobuf/google.protobuf.md @@ -1,13 +1,10 @@ ---- -title: "Protocol Buffers Well-Known Types" -weight: 830 -toc_hide: false -linkTitle: "Well-Known Types" -no_list: "true" -type: docs -description: "API documentation for the google.protobuf package." ---- - ++++ +title = "Protocol Buffers Well-Known Types" +weight = 830 +linkTitle = "Well-Known Types" +description = "API documentation for the google.protobuf package." +type = "docs" ++++ ## Index diff --git a/content/reference/protobuf/proto2-spec.md b/content/reference/protobuf/proto2-spec.md index 38082830..4adcc1e5 100644 --- a/content/reference/protobuf/proto2-spec.md +++ b/content/reference/protobuf/proto2-spec.md @@ -1,15 +1,12 @@ ---- -title: "Protocol Buffers Version 2 Language Specification" -weight: 800 -toc_hide: false -linkTitle: "Version 2 Language Specification" -no_list: "true" -type: docs -description: "This topic is a language specification reference for version 2 of the Protocol Buffers language (proto2)." ---- - -This is a language specification reference for version 2 of the Protocol Buffers -language (proto2). The syntax is specified using ++++ +title = "Protocol Buffers Version 2 Language Specification" +weight = 800 +linkTitle = "Version 2 Language Specification" +description = "This topic is a language specification reference for version 2 of the Protocol Buffers language (proto2)." +type = "docs" ++++ + +The syntax is specified using [Extended Backus-Naur Form (EBNF)](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form): ``` diff --git a/content/reference/protobuf/proto3-spec.md b/content/reference/protobuf/proto3-spec.md index 04da3da2..dec66a88 100644 --- a/content/reference/protobuf/proto3-spec.md +++ b/content/reference/protobuf/proto3-spec.md @@ -1,15 +1,12 @@ ---- -title: "Protocol Buffers Version 3 Language Specification" -weight: 810 -toc_hide: false -linkTitle: "Version 3 Language Specification" -no_list: "true" -type: docs -description: "This topic is a language specification reference for version 3 of the Protocol Buffers language (proto3)." ---- - -This is a language specification reference for version 3 of the Protocol Buffers -language (proto3). The syntax is specified using ++++ +title = "Protocol Buffers Version 3 Language Specification" +weight = 810 +linkTitle = "Version 3 Language Specification" +description = "This topic is a language specification reference for version 3 of the Protocol Buffers language (proto3)." +type = "docs" ++++ + +The syntax is specified using [Extended Backus-Naur Form (EBNF)](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form): ``` diff --git a/content/reference/protobuf/textformat-spec.md b/content/reference/protobuf/textformat-spec.md index 96cde15f..7ab08840 100644 --- a/content/reference/protobuf/textformat-spec.md +++ b/content/reference/protobuf/textformat-spec.md @@ -1,18 +1,13 @@ ---- -title: "Text Format Language Specification" -weight: 820 -toc_hide: false -linkTitle: "Text Format Language Specification" -no_list: "true" -type: docs -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." ---- - -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. This format is distinct from the format of text within a `.proto` schema, -for example. This document contains reference documentation using the syntax -specified in ++++ +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." +type = "docs" ++++ + +This format is distinct from the format of text +within a `.proto` schema, for example. This document contains reference +documentation using the syntax specified in [ISO/IEC 14977 EBNF](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form). {{% alert title="Note" color="note" %}} @@ -662,7 +657,7 @@ the schema, so they may provide various features. ```textproto # proto-file: some/proto/my_file.proto -# proto-message: MyMessage +# proto-message: some.package.MyMessage ``` ## Working with the Format Programmatically diff --git a/content/reference/python/_index.md b/content/reference/python/_index.md index 066d1d63..99f62a99 100644 --- a/content/reference/python/_index.md +++ b/content/reference/python/_index.md @@ -1,13 +1,7 @@ ---- -title: "Python Reference" -weight: 740 -toc_hide: false -linkTitle: "Python" -no_list: "true" -type: docs -description: "This section contains reference documentation for working with protocol buffer classes in Python" ---- - - -* [Python Generated Code Guide](/reference/python/python-generated) -* [Python API (Sphinx)](https://googleapis.dev/python/protobuf/latest/) ++++ +title = "Python Reference" +weight = 740 +linkTitle = "Python" +description = "This section contains reference documentation for working with protocol buffer classes in Python." +type = "docs" ++++ diff --git a/content/reference/python/python-generated.md b/content/reference/python/python-generated.md index 0ec2783d..b9ada4aa 100644 --- a/content/reference/python/python-generated.md +++ b/content/reference/python/python-generated.md @@ -1,18 +1,16 @@ ---- -title: "Python Generated Code Guide" -weight: 750 -toc_hide: false -linkTitle: "Generated Code Guide" -no_list: "true" -type: docs -description: "This topic describes exactly what Python definitions the protocol buffer compiler generates for any given protocol definition." ---- - -This page describes exactly what Python definitions the protocol buffer compiler -generates for any given protocol definition. 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 message -classes/interfaces, which are the same in both versions. You should read the ++++ +title = "Python Generated Code Guide" +weight = 750 +linkTitle = "Generated Code Guide" +description = "This topic describes exactly what Python definitions the protocol buffer 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 message classes/interfaces, which are the same in both versions. You should +read the [proto2 language guide](/programming-guides/proto) and/or [proto3 language guide](/programming-guides/proto3) before reading this document. diff --git a/content/reference/ruby/_index.md b/content/reference/ruby/_index.md index 7471df9f..9ba96096 100644 --- a/content/reference/ruby/_index.md +++ b/content/reference/ruby/_index.md @@ -1,12 +1,7 @@ ---- -title: "Ruby Reference" -weight: 770 -toc_hide: false -linkTitle: "Ruby" -no_list: "true" -type: docs -description: "This section contains reference documentation for working with protocol buffer classes in Ruby" ---- - - -* [Ruby Generated Code Guide](/reference/ruby/ruby-generated) ++++ +title = "Ruby Reference" +weight = 770 +linkTitle = "Ruby" +description = "This section contains reference documentation for working with protocol buffer classes in Ruby." +type = "docs" ++++ diff --git a/content/reference/ruby/ruby-generated.md b/content/reference/ruby/ruby-generated.md index 87b7adfc..6ae62f86 100644 --- a/content/reference/ruby/ruby-generated.md +++ b/content/reference/ruby/ruby-generated.md @@ -1,16 +1,14 @@ ---- -title: "Ruby Generated Code Guide" -weight: 780 -toc_hide: false -linkTitle: "Generated Code Guide" -no_list: "true" -type: docs -description: "This topic describes the API of message objects that the protocol buffer compiler generates for any given protocol definition." ---- - -This page describes the API of message objects that the protocol buffer compiler -generates for any given protocol definition. You should read the language guides -for [proto2](/programming-guides/proto) or ++++ +title = "Ruby Generated Code Guide" +weight = 780 +linkTitle = "Generated Code Guide" +description = "This topic describes the API of message objects that the protocol buffer compiler generates for any given protocol definition." +type = "docs" ++++ + +You should +read the language guides for +[proto2](/programming-guides/proto2) or [proto3](/programming-guides/proto3) before reading this document. diff --git a/content/support/_index.md b/content/support/_index.md index 6ebea807..1436c98d 100644 --- a/content/support/_index.md +++ b/content/support/_index.md @@ -1,22 +1,11 @@ ---- -title: "Support" -weight: 900 -toc_hide: false -linkTitle: "Support" -no_list: "true" -type: docs -description: "Get the latest news about Protocol Buffers." ---- - ++++ +title = "Support" +weight = 900 +description = "Resources to support using Protocol Buffers." +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. - - -* [Version Support](/support/version-support) -* [Migration Guide](/support/migration) -* [Cross-Version Runtime Guarantee](/support/cross-version-runtime-guarantee) -* [Support Forum](https://groups.google.com/g/protobuf) - diff --git a/content/support/cross-version-runtime-guarantee.md b/content/support/cross-version-runtime-guarantee.md index ca96a5ec..08ce5f91 100644 --- a/content/support/cross-version-runtime-guarantee.md +++ b/content/support/cross-version-runtime-guarantee.md @@ -1,13 +1,9 @@ ---- -title: "Cross-Version Runtime Guarantee" -weight: 930 -toc_hide: false -linkTitle: "Cross-Version Runtime Guarantee" -no_list: "true" -type: docs -description: "The guarantees that the language has for cross-version runtime compatibility." ---- - ++++ +title = "Cross-Version Runtime Guarantee" +weight = 930 +description = "The guarantees that the language has for cross-version runtime compatibility." +type = "docs" ++++ diff --git a/content/support/migration.md b/content/support/migration.md index eb7d6fec..3048fa14 100644 --- a/content/support/migration.md +++ b/content/support/migration.md @@ -1,17 +1,10 @@ ---- -title: "Migration Guide" -weight: 920 -toc_hide: false -linkTitle: "Migration Guide" -no_list: "true" -type: docs -description: "A list of the breaking changes made to versions of the libraries, and how to update your code to accommodate the changes." -aliases: - - /programming-guides/migration/ ---- - -This topic provides information about breaking changes in Protocol Buffers, and -gives guidance on how to update your projects to adapt to those changes. ++++ +title = "Migration Guide" +weight = 920 +description = "A list of the breaking changes made to versions of the libraries, and how to update your code to accommodate the changes." +aliases = "/programming-guides/migration/" +type = "docs" ++++ ## Compiler Changes in v22.0 {#compiler-22} @@ -108,6 +101,76 @@ notable changes include: If `protobuf_ABSL_PROVIDER` is set to `package`, we will look for a pre-installed system version of Abseil. +### Changes in GetCurrentTime Method {#getcurrenttime} + +On Windows, `GetCurrentTime()` is the name of a macro provided by the system. +Prior to v22.x, Protobuf incorrectly removed the macro definition for +`GetCurrentTime()`. That made the macro unusable for Windows developers after +including ``. Starting with v22.x, Protobuf preserves +the macro definition. This may break customer code relying on the previous +behavior, such as if they use the expression +[`google::protobuf::util::TimeUtil::GetCurrentTime()`](/reference/cpp/api-docs/google.protobuf.util.time_util.md#TimeUtil). + +To migrate your app to the new behavior, change your code to do one of the +following: + +* if the `GetCurrent` macro is defined, explicitly undefine the + `GetCurrentTime` macro +* prevent the macro expansion by using + `(google::protobuf::util::TimeUtil::GetCurrentTime)()` or a similar + expression + +#### Example: Undefining the macro + +Use this approach if you don't use the macro from Windows. + +Before: + +```cpp +#include + +void F() { + auto time = google::protobuf::util::TimeUtil::GetCurrentTime(); +} +``` + +After: + +```cpp +#include +#ifdef GetCurrent +#undef GetCurrentTime +#endif + +void F() { + auto time = google::protobuf::util::TimeUtil::GetCurrentTime(); +} + +``` + +**Example 2: Preventing macro expansion** + +Before: + +```cpp +#include + +void F() { + auto time = google::protobuf::util::TimeUtil::GetCurrentTime(); +} +``` + +After: + +```cpp +#include + +void F() { + auto time = (google::protobuf::util::TimeUtil::GetCurrentTime)(); +} + +``` + ## C++20 Support {#cpp20} Source of changes: [PR #10796](https://github.com/protocolbuffers/protobuf/pull/10796) diff --git a/content/support/version-support.md b/content/support/version-support.md index 619ff8de..23a8326d 100644 --- a/content/support/version-support.md +++ b/content/support/version-support.md @@ -1,15 +1,10 @@ ---- -title: "Version Support" -weight: 910 -toc_hide: false -linkTitle: "Version Support" -no_list: "true" -type: docs -description: "A list of the support windows provided for language implementations." -aliases: - - /version-support/ ---- - ++++ +title = "Version Support" +weight = 910 +description = "A list of the support windows provided for language implementations." +aliases = "/version-support/" +type = "docs" ++++