Support for field presence (optional fields) in proto3

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 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.

pseudomuto / protoc-gen-doc