Add documentation

[Sleavely]

Looking at a project's dependencies and realizing that it uses the amazon-cognito-identity-js package as opposed to the more common aws-sdk. Since I'm unfamiliar with it, I want to understand what my options are for refactoring the code it's used in.

I end up on the npm page, where the 32 arbitrary copy-pasta samples in the README seem old enough to drink, but I want to know what namespaces there are and what arguments the various constructors and methods actually accept, so I search for "doc" (as in "docs" or "documentation") but that only leads me to a 404 on the Webpack website. While it's a wonderful tool, it has very little to do with how my team writes code that interacts with AWS.

Describe the solution you'd like
Perhaps auto-generating some sort of actual documentation from the Typescript definition file which is apparently present in the repository?

Edit: Or merely mentioning that the typings file exists, beyond a minimal mention in the changelog. ¯\_(ツ)_/¯

Describe alternatives you've considered
Auth0

Additional context
Developers often want to understand function arguments and return values and having documentation for your package helps them do that. Links from the official AWS docs to Javascript SDK documentation only leads to documentation for the aws-sdk package.

[gergob]

Thanks for the highlight @Sleavely! Would there be a way to use the maintained aws-sdk, as I can see amazon-cognito-identity-js is archived so I am not sure how updated that is or for how long it will be still compatible with Cognito 🤔

[Sleavely]

@gergob According to the readme, the reason the amazon-archives/amazon-cognito-identity-js repo is archived is because it was merged into the amplify-js repository.

[harrysolovay]

@gergob, amazon-cognito-identity-js is still working, and is an effective way to make requests of Cognito / manage authentication state in the browser. It is a dependency of the @aws-amplify/auth package.

@Sleavely please correct me if I'm misunderstanding your issue: I believe you're requesting a more comprehensive / interlinked API reference. Hoping to use the amazon-cognito-identity-js package directly? You can do this, although we focus our energy on documenting the higher-level abstraction, @aws-amplify/auth. If you'd like different functionality, please submit a new issue to the JS repo with a description of the specific changes you'd like to see (or better yet a pull request).

I've PRed the docs' advanced auth section with more info about the purpose of related packages. Hopefully this is guiding for developers with similar questions.

Side-note: the "old enough to drink" line is gold. You must enjoy creative writing 👍

[mauerbac]

@Sleavely - did you see the response from Harry?

[Sleavely]

@mauerbac Thanks for the reminder! I opened the issue in a tab a week ago but then life got in the way, as is customary.

@harrysolovay You've understood correctly - I wished for API documentation for amazon-cognito-identity-js. Since the repo it was hosted in back then is now archived and the development moved into amplify-js, I suppose that it would make sense to provide API documentation for it as part of the Amplify docs.

While I understand that you're focusing on the higher-level abstraction, IMHO, as an outsider I don't think that your internal organizational distinction between Amplify as a whole and the amazon-cognito-identity-js package is very apparent or meaningful. If the code is developed and published from the Amplify project, the Amplify docs is where I'd look for documentation.

Edit: To clarify - we are/were using amazon-cognito-identity-js directly. I'm not sure, but I think Amplify hadn't been released at the time we started using the cognito identity package. As I alluded to in my initial comment, I was digging through an inherited project.

[harrysolovay]

@Sleavely I understand your thinking. If you want to continue to advocate for improved documentation on this topic, please first read this PR, where I did so on your behalf. The PR was met with reasonable opposition.

If you believe you can do better, we welcome PRs! & please always feel free to add me as a reviewer.

[Sleavely]

@harrysolovay Thank you for taking the time. I think your PR looks good structurally, but I agree with the comments that some of the wording could be improved.