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)
## 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));