Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

(lambda-nodejs): Documentation confusingly imports as lambda #22003

Closed
laurelmay opened this issue Sep 12, 2022 · 2 comments · Fixed by #22014
Closed

(lambda-nodejs): Documentation confusingly imports as lambda #22003

laurelmay opened this issue Sep 12, 2022 · 2 comments · Fixed by #22014
Labels
@aws-cdk/aws-lambda-nodejs documentation This is a problem with documentation. effort/small Small work item – less than a day of effort p2

Comments

@laurelmay
Copy link
Contributor

Describe the issue

In many projects, @aws-cdk/aws-lambda gets imported as lambda; this makes the code examples at https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html confusing as users may expect that the existing import they have for the aws-lambda package will work.

The documentation is not incorrect if you have your imports the same as in the default.ts-fixture file, doing

import * as lambda from '@aws-cdk/aws-lambda-nodejs';

But I'd argue that's an unlikely way for users to use this package (as they'll often still need other exported values from aws-lambda).

I'd be happy to open a PR to rename this to something like:

import * as lambdaNodejs from '@aws-ckd/aws-lambda-nodejs';

and to make corresponding updates to the README etc; but I wanted to open an issue to discuss before implementing.

Links
@laurelmay laurelmay added documentation This is a problem with documentation. needs-triage This issue or PR still needs to be triaged. labels Sep 12, 2022
@laurelmay laurelmay changed the title (lambda-nodejs): Documentation confusing imports as lambda (lambda-nodejs): Documentation confusingly imports as lambda Sep 12, 2022
@peterwoodworth
Copy link
Contributor

I think this makes a lot of sense @kylelaker, I agree with your claim that this is an unlikely way to use the package. We'd be happy to accept a PR to change our documentation to make this distinct from the lambda package! I'm not sure what the best name for the new import variable would be though, we could use what you've proposed for now and see if we can think of something better during the review of the PR

@peterwoodworth peterwoodworth added p2 effort/small Small work item – less than a day of effort and removed needs-triage This issue or PR still needs to be triaged. labels Sep 12, 2022
@laurelmay laurelmay mentioned this issue Sep 13, 2022
Merged
4 tasks
@mergify mergify bot closed this as completed in #22014 Sep 13, 2022
mergify bot pushed a commit that referenced this issue Sep 13, 2022
@laurelmay
docs: improve Lambda import names (#22014)
c0255f6 
In the `aws-lambda-nodejs`, `aws-lambda-python`, and `aws-lambda-go`
package `README`s, the code examples use `lambda` as the name to import
the package. This makes the code examples confusing because
`rosetta/default.ts-fixture` masks the `import` statement from readers
and may confuse them as to why their `lambda` import doesn't work when
they use `lambda.NodejsFunction` (or similar). The imports are changed
to `nodejs`, `python`, and `go`. While the last (`go`) is in fact a
keyword in its own language, so too is `lambda` in Python. This matches
the pattern used by other packages' examples (`aws-route53-patterns` for
example uses `patterns` as the name for its import in docs).

This change should make the docs more clear to new users, who likely
started using Lambda using `lambda.Function` and already have a `lambda`
import that won't do what they want.

Closes #22003

----

### All Submissions:

* [X] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md/#adding-new-unconventional-dependencies)

### New Features

* [ ] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/main/INTEGRATION_TESTS.md)?
	* [ ] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
@github-actions
Copy link

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.

mackalex pushed a commit to wanjacki/aws-cdk that referenced this issue Sep 15, 2022
@laurelmay
docs: improve Lambda import names (aws#22014)
debaa79 
In the `aws-lambda-nodejs`, `aws-lambda-python`, and `aws-lambda-go`
package `README`s, the code examples use `lambda` as the name to import
the package. This makes the code examples confusing because
`rosetta/default.ts-fixture` masks the `import` statement from readers
and may confuse them as to why their `lambda` import doesn't work when
they use `lambda.NodejsFunction` (or similar). The imports are changed
to `nodejs`, `python`, and `go`. While the last (`go`) is in fact a
keyword in its own language, so too is `lambda` in Python. This matches
the pattern used by other packages' examples (`aws-route53-patterns` for
example uses `patterns` as the name for its import in docs).

This change should make the docs more clear to new users, who likely
started using Lambda using `lambda.Function` and already have a `lambda`
import that won't do what they want.

Closes aws#22003

----

### All Submissions:

* [X] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md/#adding-new-unconventional-dependencies)

### New Features

* [ ] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/main/INTEGRATION_TESTS.md)?
	* [ ] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
@aws-cdk/aws-lambda-nodejs documentation This is a problem with documentation. effort/small Small work item – less than a day of effort p2
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

docs: improve Lambda import names laurelmay/aws-cdk
3 participants
@laurelmay @corymhall @peterwoodworth