feat(AIP-4236): include version in client docs

[noahdietz]

Updates requirements around generated client documentation. Specifically, the API version of an API interface, if annotated, must be included in the corresponding generated client documentation. Furthermore, if feasible, the API service's client package documentation should include a list of client-interface-version tuples, or a single sentence if all versions are identical.

Aligns use of "service" when referring to a protobuf service with "API interface" and "service" when referring to a Product's API with "API service" as defined in AIP-9.

Refactors heading structure to be a little more accessible given increase in document size. Fixes broken markdown link for the annotation.

Marks AIP as "approved".

Internal bug http://b/467066705

[noahdietz]

cc @coryan if you want to take a look and weigh in on the language adapted from the document.

[vchudnov-g]

PTAL @ my suggestions, but it looks good! Thanks for doing this.

[vchudnov-g]

Do we want to also add a clause that the if there are multiple versions, the list may be indexed by version identifier?

version-X → Service A, Service B
version-Y → Service C, Service D

[noahdietz]

Interesting, when do you think that would be better than what is suggested (individual items per-client-interface-version tuple)?

I'm not super picky, but I'd also like to minimize variance unless it is necessary (since I'm implementing this in most languages 😄 )

[vchudnov-g]

To be clear, I was suggesting an additional clause, not a replacement.

When all the services use the same version, then the suggested concise sentences is best. If there are multiple services using distinct versions, then having the reverse list might be easier to read.

Rationale: number-of-service-versions ≤ number-of-services, so indexing by the service versions will lead to a shorter list than indexing by services.

[noahdietz]

To be clear, I was suggesting an additional clause, not a replacement.

I understand, but it is one more thing to implement, one more conditional to figure out, so I want to understand when it would be most valuable.

If there are multiple services using distinct versions, then having the reverse list might be easier to read.

If there are 15 services, 14 on the same version and 1 on a different one, it might not be easier to read while trying to find one of those 14 that have the same version:

* versionA: service, service, service, service, service, service, service, service, service, service, service, service, service, service
* versionB: service

But maybe I'm nit picking. How would the client type factor into such a list? I think that is valuable information b.c it shows them exactly which client to initialize rather than having to work it out from the service name.

Rationale: number-of-service-versions ≤ number-of-services, so indexing by the service versions will lead to a shorter list than indexing by services.

So only when each service has its own version would their be a flat list? Trying to understand the heuristic that would be applied.

[vchudnov-g]

To be clear, I was suggesting an additional clause, not a replacement.

When all the services use the same version, then the suggested concise sentences is best. If there are multiple services using distinct versions, then having the reverse list might be easier to read.

Rationale: number-of-service-versions ≤ number-of-services, so indexing by the service versions will lead to a shorter list than indexing by services.