From 52b44cae49e9274ecf79f3215ca6194909dcbb30 Mon Sep 17 00:00:00 2001 From: Tsuf Cohen <39455181+tsuf239@users.noreply.github.com> Date: Wed, 6 Sep 2023 11:06:55 +0300 Subject: [PATCH] feat(docs): add variadic params to jsii docgen (#4007) closes [#3781](https://github.com/winglang/wing/issues/3781) image ## Checklist - [x] Title matches [Winglang's style guide](https://www.winglang.io/contributing/start-here/pull_requests#how-are-pull-request-titles-formatted) - [x] Description explains motivation and solution - [ ] Tests added (always) - [x] Docs updated (only required for features) - [ ] Added `pr/e2e-full` label if this feature requires end-to-end testing *By submitting this pull request, I confirm that my contribution is made under the terms of the [Wing Cloud Contribution License](https://github.com/winglang/wing/blob/main/CONTRIBUTION_LICENSE.md)*. --- .../src/docgen/transpile/transpile.ts | 5 +++++ apps/jsii-docgen/src/docgen/transpile/wing.ts | 10 +++++++++- .../__snapshots__/documentation.test.ts.snap | 16 ++++++++-------- .../view/__snapshots__/interface.test.ts.snap | 4 ++-- .../view/__snapshots__/markdown.test.ts.snap | 16 ++++++++-------- docs/docs/04-standard-library/01-cloud/queue.md | 2 +- .../04-standard-library/02-std/api-reference.md | 2 +- libs/wingsdk/.projenrc.ts | 2 +- 8 files changed, 35 insertions(+), 22 deletions(-) diff --git a/apps/jsii-docgen/src/docgen/transpile/transpile.ts b/apps/jsii-docgen/src/docgen/transpile/transpile.ts index e7bd685c294..efff36ae4e5 100644 --- a/apps/jsii-docgen/src/docgen/transpile/transpile.ts +++ b/apps/jsii-docgen/src/docgen/transpile/transpile.ts @@ -275,6 +275,11 @@ export interface TranspiledParameter { * supports that. */ readonly declaration: string; + + /** + * Is the parameter variadic + */ + readonly variadic?: boolean; } /** diff --git a/apps/jsii-docgen/src/docgen/transpile/wing.ts b/apps/jsii-docgen/src/docgen/transpile/wing.ts index 4d1b5e826c6..d95a4f2dbc1 100644 --- a/apps/jsii-docgen/src/docgen/transpile/wing.ts +++ b/apps/jsii-docgen/src/docgen/transpile/wing.ts @@ -174,6 +174,7 @@ export class WingTranspile extends transpile.TranspileBase { parentType: this.type(parameter.parentType), typeReference: typeRef, optional: parameter.optional, + variadic: parameter.spec.variadic, declaration: this.formatProperty(name, typeRef), }; } @@ -280,7 +281,14 @@ export class WingTranspile extends transpile.TranspileBase { if (tf === "Inflight") { tf = "~Inflight"; } - return `${transpiled.name}${transpiled.optional ? "?" : ""}: ${tf}`; + if (transpiled.variadic) { + tf = `Array<${tf}>`; + } + const name = transpiled.variadic + ? `...${transpiled.name}` + : transpiled.name; + + return `${name}${transpiled.optional ? "?" : ""}: ${tf}`; } private formatProperty( diff --git a/apps/jsii-docgen/test/docgen/view/__snapshots__/documentation.test.ts.snap b/apps/jsii-docgen/test/docgen/view/__snapshots__/documentation.test.ts.snap index cbef7336ede..26504ef1ef9 100644 --- a/apps/jsii-docgen/test/docgen/view/__snapshots__/documentation.test.ts.snap +++ b/apps/jsii-docgen/test/docgen/view/__snapshots__/documentation.test.ts.snap @@ -165,7 +165,7 @@ for details about allowed filter rules.", }, }, ], - "usage": "addEventNotification(event: EventType, dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void", + "usage": "addEventNotification(event: EventType, dest: IBucketNotificationDestination, ...filters: Array): void", }, Object { "displayName": "addObjectCreatedNotification", @@ -222,7 +222,7 @@ for details about allowed filter rules.", }, }, ], - "usage": "addObjectCreatedNotification(dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void", + "usage": "addObjectCreatedNotification(dest: IBucketNotificationDestination, ...filters: Array): void", }, Object { "displayName": "addObjectRemovedNotification", @@ -279,7 +279,7 @@ for details about allowed filter rules.", }, }, ], - "usage": "addObjectRemovedNotification(dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void", + "usage": "addObjectRemovedNotification(dest: IBucketNotificationDestination, ...filters: Array): void", }, Object { "displayName": "addToResourcePolicy", @@ -446,7 +446,7 @@ impossible to modify the policy of an existing bucket.", }, }, ], - "usage": "grantPublicAccess(allowedActions: str, keyPrefix?: str): Grant", + "usage": "grantPublicAccess(...allowedActions: Array, keyPrefix?: str): Grant", }, Object { "displayName": "grantPut", @@ -1600,7 +1600,7 @@ account for data recovery and cleanup later (\`RemovalPolicy.RETAIN\`). ##### \`addEventNotification\` \`\`\`wing -addEventNotification(event: EventType, dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +addEventNotification(event: EventType, dest: IBucketNotificationDestination, ...filters: Array): void \`\`\` Adds a bucket notification event destination. @@ -1647,7 +1647,7 @@ for details about allowed filter rules. ##### \`addObjectCreatedNotification\` \`\`\`wing -addObjectCreatedNotification(dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +addObjectCreatedNotification(dest: IBucketNotificationDestination, ...filters: Array): void \`\`\` Subscribes a destination to receive notifications when an object is created in the bucket. @@ -1674,7 +1674,7 @@ Filters (see onEvent). ##### \`addObjectRemovedNotification\` \`\`\`wing -addObjectRemovedNotification(dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +addObjectRemovedNotification(dest: IBucketNotificationDestination, ...filters: Array): void \`\`\` Subscribes a destination to receive notifications when an object is removed from the bucket. @@ -1767,7 +1767,7 @@ Restrict the permission to a certain key pattern (default '*'). ##### \`grantPublicAccess\` \`\`\`wing -grantPublicAccess(allowedActions: str, keyPrefix?: str): Grant +grantPublicAccess(...allowedActions: Array, keyPrefix?: str): Grant \`\`\` Allows unrestricted access to objects from this bucket. diff --git a/apps/jsii-docgen/test/docgen/view/__snapshots__/interface.test.ts.snap b/apps/jsii-docgen/test/docgen/view/__snapshots__/interface.test.ts.snap index 7a2cf8b6937..8792e6cd812 100644 --- a/apps/jsii-docgen/test/docgen/view/__snapshots__/interface.test.ts.snap +++ b/apps/jsii-docgen/test/docgen/view/__snapshots__/interface.test.ts.snap @@ -4886,7 +4886,7 @@ Object { }, }, ], - "usage": "grant(grantee: IGrantable, actions: str): Grant", + "usage": "grant(grantee: IGrantable, ...actions: Array): Grant", }, Object { "displayName": "grantPull", @@ -5312,7 +5312,7 @@ Add a policy statement to the repository's resource policy. ## \`grant\` \`\`\`wing -grant(grantee: IGrantable, actions: str): Grant +grant(grantee: IGrantable, ...actions: Array): Grant \`\`\` Grant the given principal identity permissions to perform the actions on this repository. diff --git a/apps/jsii-docgen/test/docgen/view/__snapshots__/markdown.test.ts.snap b/apps/jsii-docgen/test/docgen/view/__snapshots__/markdown.test.ts.snap index 75f47151b7c..6721cd97140 100644 --- a/apps/jsii-docgen/test/docgen/view/__snapshots__/markdown.test.ts.snap +++ b/apps/jsii-docgen/test/docgen/view/__snapshots__/markdown.test.ts.snap @@ -88,7 +88,7 @@ account for data recovery and cleanup later (\`RemovalPolicy.RETAIN\`). ##### \`addEventNotification\` \`\`\`wing -addEventNotification(event: EventType, dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +addEventNotification(event: EventType, dest: IBucketNotificationDestination, ...filters: Array): void \`\`\` Adds a bucket notification event destination. @@ -135,7 +135,7 @@ for details about allowed filter rules. ##### \`addObjectCreatedNotification\` \`\`\`wing -addObjectCreatedNotification(dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +addObjectCreatedNotification(dest: IBucketNotificationDestination, ...filters: Array): void \`\`\` Subscribes a destination to receive notifications when an object is created in the bucket. @@ -162,7 +162,7 @@ Filters (see onEvent). ##### \`addObjectRemovedNotification\` \`\`\`wing -addObjectRemovedNotification(dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +addObjectRemovedNotification(dest: IBucketNotificationDestination, ...filters: Array): void \`\`\` Subscribes a destination to receive notifications when an object is removed from the bucket. @@ -255,7 +255,7 @@ Restrict the permission to a certain key pattern (default '*'). ##### \`grantPublicAccess\` \`\`\`wing -grantPublicAccess(allowedActions: str, keyPrefix?: str): Grant +grantPublicAccess(...allowedActions: Array, keyPrefix?: str): Grant \`\`\` Allows unrestricted access to objects from this bucket. @@ -1061,7 +1061,7 @@ account for data recovery and cleanup later (\`RemovalPolicy.RETAIN\`). ##### \`addEventNotification\` \`\`\`wing -addEventNotification(event: EventType, dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +addEventNotification(event: EventType, dest: IBucketNotificationDestination, ...filters: Array): void \`\`\` Adds a bucket notification event destination. @@ -1108,7 +1108,7 @@ for details about allowed filter rules. ##### \`addObjectCreatedNotification\` \`\`\`wing -addObjectCreatedNotification(dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +addObjectCreatedNotification(dest: IBucketNotificationDestination, ...filters: Array): void \`\`\` Subscribes a destination to receive notifications when an object is created in the bucket. @@ -1135,7 +1135,7 @@ Filters (see onEvent). ##### \`addObjectRemovedNotification\` \`\`\`wing -addObjectRemovedNotification(dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +addObjectRemovedNotification(dest: IBucketNotificationDestination, ...filters: Array): void \`\`\` Subscribes a destination to receive notifications when an object is removed from the bucket. @@ -1228,7 +1228,7 @@ Restrict the permission to a certain key pattern (default '*'). ##### \`grantPublicAccess\` \`\`\`wing -grantPublicAccess(allowedActions: str, keyPrefix?: str): Grant +grantPublicAccess(...allowedActions: Array, keyPrefix?: str): Grant \`\`\` Allows unrestricted access to objects from this bucket. diff --git a/docs/docs/04-standard-library/01-cloud/queue.md b/docs/docs/04-standard-library/01-cloud/queue.md index 487b88c507a..b872a267307 100644 --- a/docs/docs/04-standard-library/01-cloud/queue.md +++ b/docs/docs/04-standard-library/01-cloud/queue.md @@ -170,7 +170,7 @@ Purge all of the messages in the queue. ##### `push` ```wing -inflight push(messages: str): void +inflight push(...messages: Array): void ``` Push one or more messages to the queue. diff --git a/docs/docs/04-standard-library/02-std/api-reference.md b/docs/docs/04-standard-library/02-std/api-reference.md index 2b54032ac6f..9066dd31faf 100644 --- a/docs/docs/04-standard-library/02-std/api-reference.md +++ b/docs/docs/04-standard-library/02-std/api-reference.md @@ -1818,7 +1818,7 @@ metadata describing how one construct is related to another construct. ##### `addDependency` ```wing -addDependency(deps: IDependable): void +addDependency(...deps: Array): void ``` Add an ordering dependency on another construct. diff --git a/libs/wingsdk/.projenrc.ts b/libs/wingsdk/.projenrc.ts index 3be8fec3b93..a770ea47b14 100644 --- a/libs/wingsdk/.projenrc.ts +++ b/libs/wingsdk/.projenrc.ts @@ -6,7 +6,7 @@ const UNDOCUMENTED_CLOUD_FILES = ["index", "test-runner"]; const cloudFiles = readdirSync("./src/cloud"); const cloudResources: Set = new Set( - cloudFiles.map((filename) => filename.split(".").slice(0, -1).join(".")) + cloudFiles.map((filename) => filename.split(".")[0]) ); UNDOCUMENTED_CLOUD_FILES.forEach((file) => cloudResources.delete(file));