Add JSDoc annotations to ably.d.ts

[owenpearson]

Resolves #848

• Adds JSDoc descriptions to the vast majority of the public API.
• Almost all of the descriptions are copied from ably.com/documentation. There are a few omissions where I couldn't find any existing public documentation.
• I haven't added @param or @returns tags anywhere, we should perhaps consider adding these in future but I didn't feel it to be essential enough to include in this PR since many of them would just be tautological (for example @param options {Options} - an instance of options doesn't really give the reader any useful information that they wouldn't already get from the TypeScript type annotations)
• Also changes all of the existing class methods to use actual class methods (before these were almost all typed as class properties with function types for some reason).
• Also added method overloads where appropriate.

[QuintinWillison]

I've spent one and a half hours reading this pull request so far, and only got to just over two thirds of the way through. I'm taking the call at this point to stop reviewing and submit the changes I've spotted so far.

While I acknowledge that much of the copy included here has been copied over from elsewhere, my feeling is that more work should have been done to ensure consistency while that was done. Things I'm spotting:

• Poor sentence structures which make even less sense when introduced into this context
• Inconsistency in the way that terms are referenced, in terms of capitalisation and code formatting - e.g. 'token params' vs 'Token Params' vs 'Token params' (may not have seen this one) vs 'TokenParams' vs 'TokenParams'
• Lack of context in some places - e.g.:
  • 'Ably' prefix on some concepts
  • external links where they might help
  • consistent specification of units (e.g. milliseconds) for properties
• Repetition - words/terms that need not be repeated in commentary because they're implicit in the property name or type

The reality is that we're very unlikely to find the time, anytime soon, to go back over all these comments and refine/correct them further. Thus, this is an opportunity to get this right and that requires significant time and effort. I think this pull request needs more time invested into it.

[mattheworiordan]

This is great work, well done @owenpearson.

Personally I think we should land it, bring all this great work to customers, and raise issues to further improve (after all we'll always be improving docs). This PR has been open since Feb, which means the work was done, but customers are not benefitting from it for months now.

[owenpearson]

@mattheworiordan Thanks 👍 The EdX pod are actually looking at formalising how we maintain/add docstrings in our SDKs and are gonna start with ably-js next sprint. IIRC the plan is for them to pick up this PR, so I'll leave it to them and hopefully it will be landed soon.
cc @Srushtika

[lawrence-forooghian]

Just a note that I'll be taking this one over, starting with resolving the merge conflicts.

[lawrence-forooghian]

I've done the following here:

• merged in main
• addressed @QuintinWillison's comment about not using the AgentOptions type (see commit message of e3eb7ad for more details)
• converted remaining function properties to methods
• documented the remaining overload we hadn't handled yet
• undone some confusing changes to package-lock.json for reviewability

I'm keen to get this one merged if possible. The merge conflicts took me several hours to resolve and I'd be very glad to not need to do it again.

In terms of @QuintinWillison's other review comments:

• he's pointed out some undocumented properties – I'll make sure we catch these when building the HTML documentation in EDX-158, and that we document these properties in EDX-149
• content of the docstrings — we'll replace these in EDX-149 anyway (with content written by tech writers), so I don't think we need to dwell on the contents

@owenpearson would you mind taking a quick look at this one to check my changes?

[lawrence-forooghian]

@owenpearson pointed out that we're going to do a release of this library soon and that it might be odd for a set of docstrings to appear and then suddenly be replaced on the next release. So I'm happy to keep this in a feature branch for now.

[lawrence-forooghian]

@QuintinWillison I've changed the target branch of this PR to integration/docs. Would you be happy for us to merge now, given that further substantial changes to the docstrings will be coming before we merge into main? If so please could you resolve your comments and approve?

[lawrence-forooghian]

Resolved @QuintinWillison’s comments (Slack message).