Include PGV validation options in bufdoc

[akshayjshah]

When generating documentation for messages with protoc-gen-validate annotations, it'd be nice to have the docs automatically include the annotations. We could do that by synthesizing an extra paragraph of text (e.g., "This field is required" or "The value must match the regexp abc.*"), by including the raw annotations (possibly with some progressive disclosure in the UI), or by some other means.

@josephschorr from Authzed brought this up in our Slack.

[bufdev]

I don't think we want to special-case protoc-gen-validate annotations:

• It's a rabbit hole - do we also special-case google.api? gogoproto? The newest library that comes out?
• protoc-gen-validate looks to be less maintained these days, and doesn't look like the long-term solution for validation.

[akshayjshah]

All reasonable concerns. OTOH, validation is reasonably common, as are the Google HTTP transcoding annotations. The validation annotations in particular are important to understand the schema, and it seems like a fairly large omission to drop them completely.

It might be sufficient to show the literal text of the annotation in a progressive disclosure dropdown.

Edit: Basically, I agree that ideally we wouldn't special-case PGV and we'd instead find some generic way to show annotations to end users. Failing that, we're choosing between docs that are incomplete in important ways, or picking and choosing plugins to special-case.

[lrewega]

There seems to be a middle ground where annotations are rendered and the associated extensions are documented inline where referenced (perhaps as a tool tip or something unobstructive). I agree special-casing is a rabbit hole -- ideally extension authors can supply descriptive documentation that is used to provide the experience proposed experience.

[josephschorr]

Since you guys have taken over protoc-gen-validate now (as per https://twitter.com/mattklein123/status/1576971951394164736), perhaps this can be special cased now? :)

[akshayjshah]

We'd still prefer to avoid special-casing PGV - we'd rather not give our plugins special treatment :) However, we are looking at the UX options for including these sorts of annotations in the generated documentation.