fix: use jsdoc link syntax (#316)

* fix: use jsdoc link syntax * add global flag in regex * run baselin test * readable name * format the method comment * continue format
googleapis · Mar 5, 2020 · b0b280f · b0b280f
1 parent e716513
commit b0b280f
Show file tree

Hide file tree

Showing 6 changed files with 163 additions and 161 deletions.
diff --git a/baselines/kms/src/v1/key_management_service_client.ts.baseline b/baselines/kms/src/v1/key_management_service_client.ts.baseline
diff --git a/baselines/monitoring/src/v3/alert_policy_service_client.ts.baseline b/baselines/monitoring/src/v3/alert_policy_service_client.ts.baseline
@@ -483,7 +483,7 @@ export class AlertPolicyServiceClient {
  *
  *       projects/[PROJECT_ID]/alertPolicies/[ALERT_POLICY_ID]
  *
- *   For more information, see [AlertPolicy][google.monitoring.v3.AlertPolicy].
+ *   For more information, see {@link google.monitoring.v3.AlertPolicy|AlertPolicy}.
  * @param {object} [options]
  *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
  * @returns {Promise} - The promise which resolves to an array.
@@ -638,7 +638,7 @@ export class AlertPolicyServiceClient {
  *   Note that this field names the parent container in which the alerting
  *   policies to be listed are stored. To retrieve a single alerting policy
  *   by name, use the
- *   [GetAlertPolicy][google.monitoring.v3.AlertPolicyService.GetAlertPolicy]
+ *   {@link google.monitoring.v3.AlertPolicyService.GetAlertPolicy|GetAlertPolicy}
  *   operation, instead.
  * @param {string} request.filter
  *   If provided, this field specifies the criteria that must be met by
@@ -735,7 +735,7 @@ export class AlertPolicyServiceClient {
  *   Note that this field names the parent container in which the alerting
  *   policies to be listed are stored. To retrieve a single alerting policy
  *   by name, use the
- *   [GetAlertPolicy][google.monitoring.v3.AlertPolicyService.GetAlertPolicy]
+ *   {@link google.monitoring.v3.AlertPolicyService.GetAlertPolicy|GetAlertPolicy}
  *   operation, instead.
  * @param {string} request.filter
  *   If provided, this field specifies the criteria that must be met by

diff --git a/baselines/monitoring/src/v3/notification_channel_service_client.ts.baseline b/baselines/monitoring/src/v3/notification_channel_service_client.ts.baseline
@@ -897,7 +897,7 @@ export class NotificationChannelServiceClient {
  *
  *   Note that this names the parent container in which to look for the
  *   descriptors; to retrieve a single descriptor by name, use the
- *   [GetNotificationChannelDescriptor][google.monitoring.v3.NotificationChannelService.GetNotificationChannelDescriptor]
+ *   {@link google.monitoring.v3.NotificationChannelService.GetNotificationChannelDescriptor|GetNotificationChannelDescriptor}
  *   operation, instead.
  * @param {number} request.pageSize
  *   The maximum number of results to return in a single response. If
@@ -983,7 +983,7 @@ export class NotificationChannelServiceClient {
  *
  *   Note that this names the parent container in which to look for the
  *   descriptors; to retrieve a single descriptor by name, use the
- *   [GetNotificationChannelDescriptor][google.monitoring.v3.NotificationChannelService.GetNotificationChannelDescriptor]
+ *   {@link google.monitoring.v3.NotificationChannelService.GetNotificationChannelDescriptor|GetNotificationChannelDescriptor}
  *   operation, instead.
  * @param {number} request.pageSize
  *   The maximum number of results to return in a single response. If
@@ -1044,7 +1044,7 @@ export class NotificationChannelServiceClient {
  *   in which to look for the notification channels; it does not name a
  *   specific channel. To query a specific channel by REST resource name, use
  *   the
- *   [`GetNotificationChannel`][google.monitoring.v3.NotificationChannelService.GetNotificationChannel]
+ *   {@link google.monitoring.v3.NotificationChannelService.GetNotificationChannel|`GetNotificationChannel`}
  *   operation.
  * @param {string} request.filter
  *   If provided, this field specifies the criteria that must be met by
@@ -1141,7 +1141,7 @@ export class NotificationChannelServiceClient {
  *   in which to look for the notification channels; it does not name a
  *   specific channel. To query a specific channel by REST resource name, use
  *   the
- *   [`GetNotificationChannel`][google.monitoring.v3.NotificationChannelService.GetNotificationChannel]
+ *   {@link google.monitoring.v3.NotificationChannelService.GetNotificationChannel|`GetNotificationChannel`}
  *   operation.
  * @param {string} request.filter
  *   If provided, this field specifies the criteria that must be met by

diff --git a/baselines/redis/src/v1beta1/cloud_redis_client.ts.baseline b/baselines/redis/src/v1beta1/cloud_redis_client.ts.baseline
@@ -501,7 +501,7 @@ export class CloudRedisClient {
  * @param {google.protobuf.FieldMask} request.updateMask
  *   Required. Mask of fields to update. At least one path must be supplied in
  *   this field. The elements of the repeated paths field may only include these
- *   fields from [Instance][google.cloud.redis.v1beta1.Instance]:
+ *   fields from {@link google.cloud.redis.v1beta1.Instance|Instance}:
  *
  *    *   `displayName`
  *    *   `labels`
@@ -850,7 +850,7 @@ export class CloudRedisClient {
  *   If not specified, a default value of 1000 will be used by the service.
  *   Regardless of the page_size value, the response may include a partial list
  *   and a caller should only rely on response's
- *   [next_page_token][CloudRedis.ListInstancesResponse.next_page_token]
+ *   {@link CloudRedis.ListInstancesResponse.next_page_token|next_page_token}
  *   to determine if there are more instances left to be queried.
  * @param {string} request.pageToken
  *   The next_page_token value returned from a previous List request,
@@ -933,7 +933,7 @@ export class CloudRedisClient {
  *   If not specified, a default value of 1000 will be used by the service.
  *   Regardless of the page_size value, the response may include a partial list
  *   and a caller should only rely on response's
- *   [next_page_token][CloudRedis.ListInstancesResponse.next_page_token]
+ *   {@link CloudRedis.ListInstancesResponse.next_page_token|next_page_token}
  *   to determine if there are more instances left to be queried.
  * @param {string} request.pageToken
  *   The next_page_token value returned from a previous List request,

diff --git a/templates/typescript_gapic/_util.njk b/templates/typescript_gapic/_util.njk
@@ -16,6 +16,8 @@ limitations under the License.
 
 -#}
 
+{% set markdownReferenceRegex = r/\[(.*?)\]\[(.*?)\]/g %}
+
 {%- macro printComments(method, service) -%}
   {{- printCommentsForMethod(method) }}
   {{- printRequest(method) -}}
@@ -37,7 +39,7 @@ limitations under the License.
 {% for line in lines %}
 {%- set trimmed = line.replace(r/\s+$/, '') -%}
 {%- if trimmed.length > 0 %}
- * {{ trimmed.replaceAll('*/', '* /') | safe}}
+ * {{ trimmed.replaceAll('*/', '* /') | replace(markdownReferenceRegex, '{@link $2|$1}') | safe }}
 {%- else %}
  *
 {%- endif %}
@@ -47,7 +49,7 @@ limitations under the License.
 {%- macro printCommentsForMethod(method) -%}
 {%- set lines = method.comments -%}
 {% for line in lines %}
- *{{ line.replaceAll('*/', '* /').replace(r/\s+$/, '') | safe}}
+ *{{ line.replaceAll('*/', '* /').replace(r/\s+$/, '') | replace(markdownReferenceRegex, '{@link $2|$1}') | safe }}
 {%- endfor %}
 {%- endmacro -%}
 
@@ -87,7 +89,7 @@ limitations under the License.
 {%- for line in lines %}
 {%- set trimmed = line.replace(r/\s+$/, '') -%}
 {%- if trimmed.length > 0 %}
- *  {{ trimmed.replaceAll('*/', '* /') | safe}}
+ *  {{ trimmed.replaceAll('*/', '* /') | replace(markdownReferenceRegex, '{@link $2|$1}') | safe }}
 {%- else %}
  *
 {%- endif -%}

diff --git a/templates/typescript_gapic/src/$version/$service_client.ts.njk b/templates/typescript_gapic/src/$version/$service_client.ts.njk
@@ -548,7 +548,7 @@ export class {{ service.name }}Client {
    * Return a fully-qualified {{ template.name.toCamelCase() }} resource name string.
    *
 {%- for param in template.params %}
-   * @param {string} {{ param }}
+   * @param {string} {{ param | replace(regExp, '{@link $2|$1}') }}
 {%- endfor %}
    * @returns {string} Resource name string.
    */