In Protobuf 3.12, one must pass the --experimental_allow_proto3_optional flag to protoc in order for optional fields to compile. This flag requires that all code generator plugins used include support for proto3 optional fields, otherwise compilation fails.
For example, this is the error when using protoc-gen-go to generate documentation for a file containing an optional field:
$ protoc --experimental_allow_proto3_optional features.proto --doc_out=.
features.proto: is a proto3 file that contains optional fields, but code generator
protoc-gen-doc hasn't been updated to support optional fields in proto3. Please
ask the owner of this code generator to support proto3 optional.--doc_out:
Per the above-linked implementation guide, ideally this behavior would be GA and no longer behind a flag in Protobuf 3.13.
Issue
This issue is to request that protoc-gen-doc support proto3 optional fields.
Functionality
We would need to answer the question of how proto3 optional fields should be treated by protoc-gen-doc. Per the implementation guide, code generators that support proto2 should generate the same code for proto3 optional fields as proto2 optional fields.
This would suggest that the only update should be that the documentation include the label "optional" for proto3 optional fields (as occurs for proto2 optional fields). Of course proto3 fields that are not explicitly annotated as optional should be unaffected and should continue to have no label (unless repeated).
Implementation
I'm working on a pull request to implement the above suggestion for functionality, but wanted to open an issue in case there's a desire for a broader discussion about what the functionality should be.
Overview
Protobuf 3.12 includes experimental support for field presence via the
optional
keyword.There is a guide for how to implement field presence in code generators.
In Protobuf 3.12, one must pass the
--experimental_allow_proto3_optional
flag toprotoc
in order foroptional
fields to compile. This flag requires that all code generator plugins used include support for proto3 optional fields, otherwise compilation fails.For example, this is the error when using
protoc-gen-go
to generate documentation for a file containing an optional field:Per the above-linked implementation guide, ideally this behavior would be GA and no longer behind a flag in Protobuf 3.13.
Issue
This issue is to request that
protoc-gen-doc
support proto3 optional fields.Functionality
We would need to answer the question of how
proto3
optional fields should be treated byprotoc-gen-doc
. Per the implementation guide, code generators that supportproto2
should generate the same code forproto3
optional fields asproto2
optional fields.This would suggest that the only update should be that the documentation include the label "optional" for proto3 optional fields (as occurs for
proto2
optional fields). Of courseproto3
fields that are not explicitly annotated as optional should be unaffected and should continue to have no label (unlessrepeated
).Implementation
I'm working on a pull request to implement the above suggestion for functionality, but wanted to open an issue in case there's a desire for a broader discussion about what the functionality should be.