Maintenance: review API docs & README across repo

[dreamorosi]

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:

• Maintenance: review API docs & README for Logger #2374
• Maintenance: review API docs & README for Metrics #2375
• Maintenance: review API docs & README for Tracer #2376
• Maintenance: review API docs & README for Commons #2377
• Maintenance: review API docs & README for Parameters #2378
• Maintenance: review API docs & README for Idempotency #2379
• Maintenance: review API docs & README for Batch #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 the package.json are referenced in the entryPoints list of the package's typed.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) vs Calculates 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
• 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

• 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.