powertools-lambda-typescript
powertools-lambda-typescript copied to clipboard
Maintenance: review API docs & README across repo
Summary
Some of the README files in the repo could use some polishing and focus, especially the ones for the core utilities that are older. Customers finding the packages on npmjs.com want to know what the package can do and whether it can help solve their requirements, not learn about Powertools as a whole.
Likewise, customers using the API docs need to be able to get the right level of info for all the public methods, types, functions, etc. that are exported. This is not the case today and some of them are either not included in the API docs or under documented.
Since I expect this type of effort to touch several files I am breaking down the work in smaller units.
Below a list of issues to tackle this topic:
- #2374
- #2375
- #2376
- #2377
- #2378
- #2379
- #2380
In addition to the above, before closing this issue, we should also:
- [ ] document the rules below + any other that was applied in the "Processes" section of the docs
- [ ] exclude any private package from the main
typedoc.json
file at the root of the project
Why is this needed?
So that customers finding the package on npm or using the API docs have the right level of details.
Which area does this relate to?
Other
Solution
For the README files, the structure should be similar to the one found in the JMESPath utility which is more recent, that is:
- One liner about the utility & Powertools
- Table of contents
- Usage / Install
- Basic features with code samples
- Additional most important / useful features wit code samples
- Contribute - Roadmap - Connect - Supporting Powertools + customer references
- License
For the API Docs we should ensure that:
- all the files exported in the
exports
section of thepackage.json
are referenced in theentryPoints
list of the package'styped.json
- there are no warnings or errors when rendering the API docs
- public methods have:
- each parameter documented using this format
@param name description
-
@returns
is not present since it's inferred by TypeScript - there's a one-liner description using infinite tense i.e.
Calculate the average
(correct) vsCalculates the average
(wrong) - if the method is complex or has side effect, has additional info that would be useful for a customer in the IDE
- where relevant, link to other functions/types/modules using
{@link url | title} notation
- especially for public methods that can be used directly by customers, provide one or more code example using
@example
notation
- each parameter documented using this format
- class properties have a comment explaining what they do (example), if they have default value document which using
@default
- types & interfaces have comments w/ documentation using the same conventions as above
Acknowledgment
- [X] This request meets Powertools for AWS Lambda (TypeScript) Tenets
- [ ] Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET
Future readers
Please react with 👍 and your use case to help us understand customer demand.