add protodoc annotations

[lizan]

Signed-off-by: Lizan Zhou [email protected]

[htuch]

So, this actually gets to a pivotal issue. UDPA should be generally client agnostic, so shouldn't reflect Envoy implementation status. I think the other annotations are generic API evolution, but this one is Envoy specific. So, I'd suggest we put this in the Envoy repo for now. For UDPA fields that are not in Envoy, we're going to have to figure out some story, but it's probably outside the scope of what we care about for v3.

[lizan]

Well I agree that "is this feature implemented" is specific to each implementation but not to Envoy, so that's why I posted the annotation here. Another reason is I think we will end moving our proto tools here (including protoxform/protodoc). The pivotal issue is how to mark an UDPA message not implemented (by each implementation) but not where this annotation lives.

[htuch]

I think consuming projects are going to have to consume some baseline tools for working with protos and the common docs form UDPA, and then overlay their own additional customizations before generating docs. I actually think there are a number of viable alternatives here, e.g. we could have each doc produce its own doc tree, with common source, or we could have various projects provide overlays and generate one central set of docs with federated responsibility for communicating what is implemented.

Either way, we won't have a commit to the UDPA repository every time a new field is added or removed.

I'll add this to the agenda for the next UDPA-WG, we should discuss more. Meanwhile, I recommend moving this annotation back to Envoy. CC @mattklein123

[mattklein123]

I agree that this is a really messy topic and one we have to think about deeply. For now I agree we should move it back until we figure out the overlay situation.