Improve docstring rendering (#677)

* Produce better docstrings

Remove the HTML escape handled by typedoc and indent data correctly.

* Remove from type as well.

* Remove empty lines

* Do models as well

* pre-commit fixes

Co-authored-by: ci.datadog-api-spec <[email protected]>

Author: therve

.generator/src/generator/cli.py

@@ -45,7 +45,7 @@ def cli(input, output):
     env.filters["form_parameter"] = openapi.form_parameter
     env.filters["untitle_case"] = formatter.untitle_case
     env.filters["response_type"] = openapi.get_type_for_response
-    env.filters["escape_html"] = formatter.escape_html
+    env.filters["docstring"] = formatter.docstring
 
     env.globals["get_references_for_model"] = openapi.get_references_for_model
     env.globals["package_name"] = package_name

.generator/src/generator/formatter.py

@@ -72,17 +72,6 @@
     "yield",
 }
 
-HTML_ESCAPE_CHARACTERS = {
-    "&": "&",
-    "'": "'",
-    ">": ">",
-    "<": "&lt;",
-    '"': "&quot;",
-    "`": "&#x60;",
-    "=": "&#x3D;",
-    "\\": "\\\\",
-}
-
 with (pathlib.Path(__file__).parent / "replacement.json").open() as f:
     EDGE_CASES = json.load(f)
 
@@ -397,11 +386,11 @@ def format_data_with_schema_dict(
     return f"{{\n{parameters}}}"
 
 
-def escape_html(text):
+def docstring(text, indent=3):
     if not text:
         return ""
-    text = " ".join(text.splitlines())
-    return "".join(HTML_ESCAPE_CHARACTERS.get(c, c) for c in text)
+    blank = " " * indent
+    return "\n".join("{}* {}".format(blank, line) for line in text.splitlines())
 
 
 def simple_type(schema):

.generator/src/generator/templates/api/api.j2

@@ -224,16 +224,20 @@ export interface {{ className }}{{ operation.operationId }}Request {
   {%- for name, parameter in requiredParams %}
   {%- set parameterType = get_type_for_parameter(parameter) %}
   /**
-   * {{ parameter.description|escape_html }}
-   * @type {{ parameterType|escape_html }}
+{%- if parameter.description %}
+{{ parameter.description|docstring }}
+{%- endif %}
+   * @type {{ parameterType }}
    */
   {{ name|attribute_name }}{%- if not parameter.required %}?{%-endif %}: {{ parameterType }}
   {%-endfor %}
   {%- for name, parameter in optionalParams %}
   {%- set parameterType = get_type_for_parameter(parameter) %}
   /**
-   * {{ parameter.description|escape_html }}
-   * @type {{ parameterType|escape_html }}
+{%- if parameter.description %}
+{{ parameter.description|docstring }}
+{%- endif %}
+   * @type {{ parameterType }}
    */
   {{ name|attribute_name }}{%- if not parameter.required %}?{%-endif %}: {{ parameterType }}
   {%-endfor %}
@@ -261,7 +265,7 @@ export class {{ className }} {
 
   /**
    {%- if operation.description %}
-   * {{ operation.description|replace("\n", " ") }}
+{{ operation.description|docstring }}
    {%- endif %}
    * @param param The request object
    */

.generator/src/generator/templates/model/model.j2

@@ -14,7 +14,7 @@ import { AttributeTypeMap{%- if "oneOf" in model %}, UnparsedObject{% endif %} }
 
 {% if "description" in model %}
 /**
-* {{ model.description|replace("\n", " ") }}
+{{ model.description|docstring(indent=1) }}
 */
 {% endif %}
 {%- if "enum" not in model and "oneOf" not in model -%}
@@ -24,7 +24,7 @@ export class {{ name }} {
 {%- set isNullable = schema.nullable %}
 {%- if schema.description %}
   /**
-  * {{ schema.description|replace("\n", " ") }}
+{{ schema.description|docstring }}
   */
 {%- endif %}
   "{{ attr|attribute_name }}"{%- if not isRequired %}?{%- endif %}: {{ type_to_typescript(schema) }}{%- if isRequired and isNullable %}|null{%- endif %};

packages/datadog-api-client-v1/apis/AWSIntegrationApi.ts

@@ -1009,15 +1009,18 @@ export interface AWSIntegrationApiCreateAWSAccountRequest {
 
 export interface AWSIntegrationApiCreateAWSTagFilterRequest {
   /**
-   * Set an AWS tag filter using an `aws_account_identifier`, `namespace`, and filtering string. Namespace options are `application_elb`, `elb`, `lambda`, `network_elb`, `rds`, `sqs`, and `custom`.
+   * Set an AWS tag filter using an `aws_account_identifier`, `namespace`, and filtering string.
+   * Namespace options are `application_elb`, `elb`, `lambda`, `network_elb`, `rds`, `sqs`, and `custom`.
    * @type AWSTagFilterCreateRequest
    */
   body: AWSTagFilterCreateRequest;
 }
 
 export interface AWSIntegrationApiCreateNewAWSExternalIDRequest {
   /**
-   * Your Datadog role delegation name. For more information about your AWS account Role name, see the [Datadog AWS integration configuration info](https://docs.datadoghq.com/integrations/amazon_web_services/#setup).
+   * Your Datadog role delegation name.
+   * For more information about your AWS account Role name,
+   * see the [Datadog AWS integration configuration info](https://docs.datadoghq.com/integrations/amazon_web_services/#setup).
    * @type AWSAccount
    */
   body: AWSAccount;
@@ -1033,15 +1036,15 @@ export interface AWSIntegrationApiDeleteAWSAccountRequest {
 
 export interface AWSIntegrationApiDeleteAWSTagFilterRequest {
   /**
-   * Delete a tag filtering entry for a given AWS account and `dd-aws` namespace.
+   * Delete a tag filtering entry for a given AWS account and `dd-aws` namespace.
    * @type AWSTagFilterDeleteRequest
    */
   body: AWSTagFilterDeleteRequest;
 }
 
 export interface AWSIntegrationApiListAWSAccountsRequest {
   /**
-   * Only return AWS accounts that matches this `account_id`.
+   * Only return AWS accounts that matches this `account_id`.
    * @type string
    */
   accountId?: string;
@@ -1051,15 +1054,15 @@ export interface AWSIntegrationApiListAWSAccountsRequest {
    */
   roleName?: string;
   /**
-   * Only return AWS accounts that matches this `access_key_id`.
+   * Only return AWS accounts that matches this `access_key_id`.
    * @type string
    */
   accessKeyId?: string;
 }
 
 export interface AWSIntegrationApiListAWSTagFiltersRequest {
   /**
-   * Only return AWS filters that matches this `account_id`.
+   * Only return AWS filters that matches this `account_id`.
    * @type string
    */
   accountId: string;
@@ -1072,17 +1075,19 @@ export interface AWSIntegrationApiUpdateAWSAccountRequest {
    */
   body: AWSAccount;
   /**
-   * Only return AWS accounts that matches this `account_id`.
+   * Only return AWS accounts that matches this `account_id`.
    * @type string
    */
   accountId?: string;
   /**
-   * Only return AWS accounts that match this `role_name`. Required if `account_id` is specified.
+   * Only return AWS accounts that match this `role_name`.
+   * Required if `account_id` is specified.
    * @type string
    */
   roleName?: string;
   /**
-   * Only return AWS accounts that matches this `access_key_id`. Required if none of the other two options are specified.
+   * Only return AWS accounts that matches this `access_key_id`.
+   * Required if none of the other two options are specified.
    * @type string
    */
   accessKeyId?: string;
@@ -1106,7 +1111,10 @@ export class AWSIntegrationApi {
   }
 
   /**
-   * Create a Datadog-Amazon Web Services integration. Using the `POST` method updates your integration configuration by adding your new configuration to the existing one in your Datadog organization. A unique AWS Account ID for role based authentication.
+   * Create a Datadog-Amazon Web Services integration.
+   * Using the `POST` method updates your integration configuration
+   * by adding your new configuration to the existing one in your Datadog organization.
+   * A unique AWS Account ID for role based authentication.
    * @param param The request object
    */
   public createAWSAccount(

packages/datadog-api-client-v1/apis/AWSLogsIntegrationApi.ts

@@ -779,7 +779,14 @@ export class AWSLogsIntegrationApi {
   }
 
   /**
-   * Test if permissions are present to add a log-forwarding triggers for the given services and AWS account. The input is the same as for Enable an AWS service log collection. Subsequent requests will always repeat the above, so this endpoint can be polled intermittently instead of blocking.  - Returns a status of 'created' when it's checking if the Lambda exists in the account. - Returns a status of 'waiting' while checking. - Returns a status of 'checked and ok' if the Lambda exists. - Returns a status of 'error' if the Lambda does not exist.
+   * Test if permissions are present to add a log-forwarding triggers for the given services and AWS account. The input
+   * is the same as for Enable an AWS service log collection. Subsequent requests will always repeat the above, so this
+   * endpoint can be polled intermittently instead of blocking.
+   *
+   * - Returns a status of 'created' when it's checking if the Lambda exists in the account.
+   * - Returns a status of 'waiting' while checking.
+   * - Returns a status of 'checked and ok' if the Lambda exists.
+   * - Returns a status of 'error' if the Lambda does not exist.
    * @param param The request object
    */
   public checkAWSLogsLambdaAsync(
@@ -802,7 +809,16 @@ export class AWSLogsIntegrationApi {
   }
 
   /**
-   * Test if permissions are present to add log-forwarding triggers for the given services and AWS account. Input is the same as for `EnableAWSLogServices`. Done async, so can be repeatedly polled in a non-blocking fashion until the async request completes.  - Returns a status of `created` when it's checking if the permissions exists   in the AWS account. - Returns a status of `waiting` while checking. - Returns a status of `checked and ok` if the Lambda exists. - Returns a status of `error` if the Lambda does not exist.
+   * Test if permissions are present to add log-forwarding triggers for the
+   * given services and AWS account. Input is the same as for `EnableAWSLogServices`.
+   * Done async, so can be repeatedly polled in a non-blocking fashion until
+   * the async request completes.
+   *
+   * - Returns a status of `created` when it's checking if the permissions exists
+   *   in the AWS account.
+   * - Returns a status of `waiting` while checking.
+   * - Returns a status of `checked and ok` if the Lambda exists.
+   * - Returns a status of `error` if the Lambda does not exist.
    * @param param The request object
    */
   public checkAWSLogsServicesAsync(

packages/datadog-api-client-v1/apis/AzureIntegrationApi.ts

@@ -543,7 +543,7 @@ export interface AzureIntegrationApiDeleteAzureIntegrationRequest {
 
 export interface AzureIntegrationApiUpdateAzureHostFiltersRequest {
   /**
-   * Update a Datadog-Azure integration's host filters request body.
+   * Update a Datadog-Azure integration's host filters request body.
    * @type AzureAccount
    */
   body: AzureAccount;
@@ -575,7 +575,13 @@ export class AzureIntegrationApi {
   }
 
   /**
-   * Create a Datadog-Azure integration.  Using the `POST` method updates your integration configuration by adding your new configuration to the existing one in your Datadog organization.  Using the `PUT` method updates your integration configuration by replacing your current configuration with the new one sent to your Datadog organization.
+   * Create a Datadog-Azure integration.
+   *
+   * Using the `POST` method updates your integration configuration by adding your new
+   * configuration to the existing one in your Datadog organization.
+   *
+   * Using the `PUT` method updates your integration configuration by replacing your
+   * current configuration with the new one sent to your Datadog organization.
    * @param param The request object
    */
   public createAzureIntegration(
@@ -656,7 +662,9 @@ export class AzureIntegrationApi {
   }
 
   /**
-   * Update a Datadog-Azure integration. Requires an existing `tenant_name` and `client_id`. Any other fields supplied will overwrite existing values. To overwrite `tenant_name` or `client_id`, use `new_tenant_name` and `new_client_id`. To leave a field unchanged, do not supply that field in the payload.
+   * Update a Datadog-Azure integration. Requires an existing `tenant_name` and `client_id`.
+   * Any other fields supplied will overwrite existing values. To overwrite `tenant_name` or `client_id`,
+   * use `new_tenant_name` and `new_client_id`. To leave a field unchanged, do not supply that field in the payload.
    * @param param The request object
    */
   public updateAzureIntegration(

packages/datadog-api-client-v1/apis/DashboardsApi.ts

@@ -799,12 +799,14 @@ export interface DashboardsApiGetDashboardRequest {
 
 export interface DashboardsApiListDashboardsRequest {
   /**
-   * When `true`, this query only returns shared custom created or cloned dashboards.
+   * When `true`, this query only returns shared custom created
+   * or cloned dashboards.
    * @type boolean
    */
   filterShared?: boolean;
   /**
-   * When `true`, this query returns only deleted custom-created or cloned dashboards. This parameter is incompatible with `filter[shared]`.
+   * When `true`, this query returns only deleted custom-created
+   * or cloned dashboards. This parameter is incompatible with `filter[shared]`.
    * @type boolean
    */
   filterDeleted?: boolean;
@@ -849,7 +851,8 @@ export class DashboardsApi {
   }
 
   /**
-   * Create a dashboard using the specified options. When defining queries in your widgets, take note of which queries should have the `as_count()` or `as_rate()` modifiers appended. Refer to the following [documentation](https://docs.datadoghq.com/developers/metrics/type_modifiers/?tab=count#in-application-modifiers) for more information on these modifiers.
+   * Create a dashboard using the specified options. When defining queries in your widgets, take note of which queries should have the `as_count()` or `as_rate()` modifiers appended.
+   * Refer to the following [documentation](https://docs.datadoghq.com/developers/metrics/type_modifiers/?tab=count#in-application-modifiers) for more information on these modifiers.
    * @param param The request object
    */
   public createDashboard(
@@ -933,7 +936,10 @@ export class DashboardsApi {
   }
 
   /**
-   * Get all dashboards.  **Note**: This query will only return custom created or cloned dashboards. This query will not return preset dashboards.
+   * Get all dashboards.
+   *
+   * **Note**: This query will only return custom created or cloned dashboards.
+   * This query will not return preset dashboards.
    * @param param The request object
    */
   public listDashboards(

packages/datadog-api-client-v1/apis/EventsApi.ts

@@ -404,7 +404,7 @@ export interface EventsApiListEventsRequest {
    */
   end: number;
   /**
-   * Priority of your events, either `low` or `normal`.
+   * Priority of your events, either `low` or `normal`.
    * @type EventPriority
    */
   priority?: EventPriority;
@@ -419,17 +419,21 @@ export interface EventsApiListEventsRequest {
    */
   tags?: string;
   /**
-   * Set unaggregated to `true` to return all events within the specified [`start`,`end`] timeframe. Otherwise if an event is aggregated to a parent event with a timestamp outside of the timeframe, it won't be available in the output. Aggregated events with `is_aggregate=true` in the response will still be returned unless exclude_aggregate is set to `true.`
+   * Set unaggregated to `true` to return all events within the specified [`start`,`end`] timeframe.
+   * Otherwise if an event is aggregated to a parent event with a timestamp outside of the timeframe,
+   * it won't be available in the output. Aggregated events with `is_aggregate=true` in the response will still be returned unless exclude_aggregate is set to `true.`
    * @type boolean
    */
   unaggregated?: boolean;
   /**
-   * Set `exclude_aggregate` to `true` to only return unaggregated events where `is_aggregate=false` in the response. If the `exclude_aggregate` parameter is set to `true`, then the unaggregated parameter is ignored and will be `true` by default.
+   * Set `exclude_aggregate` to `true` to only return unaggregated events where `is_aggregate=false` in the response. If the `exclude_aggregate` parameter is set to `true`,
+   * then the unaggregated parameter is ignored and will be `true` by default.
    * @type boolean
    */
   excludeAggregate?: boolean;
   /**
-   * By default 1000 results are returned per request. Set page to the number of the page to return with `0` being the first page. The page parameter can only be used when either unaggregated or exclude_aggregate is set to `true.`
+   * By default 1000 results are returned per request. Set page to the number of the page to return with `0` being the first page. The page parameter can only be used
+   * when either unaggregated or exclude_aggregate is set to `true.`
    * @type number
    */
   page?: number;
@@ -453,7 +457,8 @@ export class EventsApi {
   }
 
   /**
-   * This endpoint allows you to post events to the stream. Tag them, set priority and event aggregate them with other events.
+   * This endpoint allows you to post events to the stream.
+   * Tag them, set priority and event aggregate them with other events.
    * @param param The request object
    */
   public createEvent(
@@ -474,7 +479,10 @@ export class EventsApi {
   }
 
   /**
-   * This endpoint allows you to query for event details.  **Note**: If the event you’re querying contains markdown formatting of any kind, you may see characters such as `%`,`\`,`n` in your output.
+   * This endpoint allows you to query for event details.
+   *
+   * **Note**: If the event you’re querying contains markdown formatting of any kind,
+   * you may see characters such as `%`,`\`,`n` in your output.
    * @param param The request object
    */
   public getEvent(
@@ -495,7 +503,15 @@ export class EventsApi {
   }
 
   /**
-   * The event stream can be queried and filtered by time, priority, sources and tags.  **Notes**: - If the event you’re querying contains markdown formatting of any kind, you may see characters such as `%`,`\`,`n` in your output.  - This endpoint returns a maximum of `1000` most recent results. To return additional results, identify the last timestamp of the last result and set that as the `end` query time to paginate the results. You can also use the page parameter to specify which set of `1000` results to return.
+   * The event stream can be queried and filtered by time, priority, sources and tags.
+   *
+   * **Notes**:
+   * - If the event you’re querying contains markdown formatting of any kind,
+   * you may see characters such as `%`,`\`,`n` in your output.
+   *
+   * - This endpoint returns a maximum of `1000` most recent results. To return additional results,
+   * identify the last timestamp of the last result and set that as the `end` query time to
+   * paginate the results. You can also use the page parameter to specify which set of `1000` results to return.
    * @param param The request object
    */
   public listEvents(

packages/datadog-api-client-v1/apis/GCPIntegrationApi.ts

@@ -522,7 +522,10 @@ export class GCPIntegrationApi {
   }
 
   /**
-   * Update a Datadog-GCP integrations host_filters and/or auto-mute. Requires a `project_id` and `client_email`, however these fields cannot be updated. If you need to update these fields, delete and use the create (`POST`) endpoint. The unspecified fields will keep their original values.
+   * Update a Datadog-GCP integrations host_filters and/or auto-mute.
+   * Requires a `project_id` and `client_email`, however these fields cannot be updated.
+   * If you need to update these fields, delete and use the create (`POST`) endpoint.
+   * The unspecified fields will keep their original values.
    * @param param The request object
    */
   public updateGCPIntegration(