Generator doxygen comments include broken links

[coryan]

The documentation as rendered looks like this:

https://googleapis.dev/cpp/google-cloud-iam/1.33.0/classgoogle_1_1cloud_1_1iam_1_1IAMClient.html#a317a11faf4b5ad519550a6764dcfac3c

It seems like this is attempting to use markdown link aliases, e.g. [ServiceAccount][google.iam.admin.v1.ServiceAccount], but the link aliases are not defined in the Doxygen block:

google-cloud-cpp/google/cloud/iam/iam_client.h

Lines 106 to 121 in 7bcb5f7

	/**
	* Creates a [ServiceAccount][google.iam.admin.v1.ServiceAccount].
	*
	* @param name Required. The resource name of the project associated with the
	* service accounts, such as `projects/my-project-123`.
	* @param account_id Required. The account id that is used to generate the
	* service account email address and a stable unique id. It is unique within a
	* project, must be 6-30 characters long, and match the regular expression
	* `[a-z]([-a-z0-9]*[a-z0-9])` to comply with RFC1035.
	* @param service_account The
	* [ServiceAccount][google.iam.admin.v1.ServiceAccount] resource to create.
	* Currently, only the following values are user assignable: `display_name`
	* and `description`.
	* @return
	* [google::iam::admin::v1::ServiceAccount](https://github.com/googleapis/googleapis/blob/9bac62dbc7a1f7b19baf578d6fbb550dbaff0d49/google/iam/admin/v1/iam.proto#L461)
	*/

Note that the previous references are to the v1.33.0 release, but this is still the case on main.

[coryan]

Ah, it seems these link aliases are taken verbatim from the proto comments:

https://github.com/googleapis/googleapis/blob/9a04fde55ca0b57bdb34cbc1716e52274a690169/google/iam/admin/v1/iam.proto#L79

[coryan]

Since this is just copying the comments verbatim, it is really a feature request, not a bug.

[coryan]

One possible "fix" is to make these links not look like links. Maybe the move to stored the docs in cloud.google.com will fix this too.

[coryan]

This looks fixed.

[coryan]

It is not fixed, for example look at:

https://googleapis.dev/cpp/google-cloud-secretmanager/latest/classgoogle_1_1cloud_1_1secretmanager_1_1SecretManagerServiceClient.html#aab81903782c1a0f0354bbfd851ace46d

Apparently I fixed the request and response types used in each method, but not any additional references.