Envoy: Fix untitled protos in API docs

[htuch]

As per screenshot, there's a bunch of protos that are in the build that don't have human readable title or helpful proto level comments (in some cases). We should do a manual pass over the API docs and fix these.

[dichen16]

Hi @htuch,
I really want to get involved, but I feel confused about your description. can u give some example of "untitled protos"?

[htuch]

I forgot to attach the screenshot :) Here it is.. the untitled protos are things like "envoy/api/v2/srds.proto", which you can see in this screenshot.

[dichen16]

Hi @htuch
I'd like to take it, could u assign it to me?

[dichen16]

Hi @htuch,
I am confused about the label "v3 API",
I saw the document, there's only v2 API related stuff.

So my question is this task is for v2 API related proto, right?

[htuch]

@dichen16 correct, we've moved most v2 issues to v3 in preparation for the upcoming v3 support.

[dichen16]

Hi @htuch,
I found all the protodoc-title are well defined,
for example,
the protodoc-title of api/envoy/api/v2/srds.proto is HTTP scoped routing configuration,
and the protodoc-title of api/envoy/api/v2/cluster/filter.proto is Upstream filters,

kind confused, Are those protodoc-title fields that this task need to upgrade?

[htuch]

@dichen16 it's the files that are missing protodoc titles that need to be populated, see my example and look at its proto.

[dichen16]

@htuch
you mean "envoy/api/v2/srds.proto", is this already well-defined?

I think it's kind different with your example, "envoy/api/v2/srds.proto".

[derekargueta]

That specific example might've been fixed by https://github.com/envoyproxy/envoy/pull/8678 but there are other instances that need fixing, such as

• https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/cluster/filter.proto
• https://www.envoyproxy.io/docs/envoy/latest/api-v2/admin/v2alpha/tap.proto
• https://www.envoyproxy.io/docs/envoy/latest/api-v2/service/discovery/v2/ads.proto

to name a few. Almost anywhere on https://www.envoyproxy.io/docs/envoy/latest/api-v2/api where you see .proto, likely implies a missing protodoc title.

[mattklein123]

For whoever works on this, let's please actually enforce this in the proto transform / format tool and then make the format check fail?