Fix and improve JSdoc types #70

Could become another issue.

ESLint is moving to FlatConfig:

https://eslint.org/blog/2023/11/whats-coming-in-eslint-9.0.0/

This PR is already large enough. Shall I file another issue for it?

Thanks for the link, looked at it, still not entirely sure what flat config is. In any case, eslint 9.0.0 is not out yet so let's keep the config change for a different PR. Do file an issue for it!

Filed #72

This appears to be unused in the file.

Crap, always check all the files before committing... Fixed

You might want to pass in two strings as both are required.

Be aware that there's a difference between @param {object} (a literal: {}) and @param {*} (that is: any) in JSDoc.

My hunch is that you want * here.

It doesn't return an Error, but throws it.

Should also indiciate | null to avoid Null Pointer Exceptions.

This might be superfluous (the const variable declaration should allow to infer this)

Is this notation to reference still required with the plugin you installed?

Using this notation somehow did not create link, remove the module: notation and now the link works, nice find

Ah, that's right. eslint didn't like it without the module:. Ah well, getting rid of the whole link tag

--edit

I got rid of the link. I'll let you resolve this conversation if this solution suits you too

Sure. Let's roll with this and wait for feedback.

const xmpp = client({ ...params }) might also work.

Ah, so that's how that works. Indeed works

In case you want to learn more: Spread syntax

I'd recommend to either stick to string[] or Array<string> notation.

Changed everything to Array<Type>

You can even document the default value:

@param {string}] [keyserverDomain='keys.openpgp.org'] - Domain of the keyserver

Strictly speaking it's the hostname.

eslint says no (that's why I removed it in this PR):

 35:1 warning Defaults are not permitted on @param jsdoc/no-defaults

This rule baffles me, jsdoc documentation clearly states default values exist

As per https://github.com/gajus/eslint-plugin-jsdoc/blob/main/.README/rules/no-defaults.md, it is not that defaults don't exist but rather that the default could be inferred in this situation as it is explicitly defined with es6 notation

Alright, then we can mark this as resolved because I did add the default value using es6 notation

@public should be the default and therefore is not needed.

I very much prefer a blank line between the subject and the description of a doclet. However, you don't follow this everywhere, so you might want to be consistent.

We could add a blank line in all the places, is fine by me. However, this is not a blank line between subject and description:

 * ASPE service provider
 *
 * Link: [Keyoxide documentation](https://docs.keyoxide.org/service-providers/aspe/)

This was simply a blank line to separate two lines of the header. I used markdown's usual two spaces but then the linter yelled at me. I'll turn it into line with @link

Might as well be a @link.

You might want to add a @license for good measure.

Added a @license to the module in index.js. I assume this is sufficient? We could add it to every module if that's preferred

I'll leave it as is and see what feedback comes in. If you were to add it to every file, @author, @copyright etc. could be added as well. Not sure whether people will consider it important.

Perhaps ask for feedback once the new documentation is live.

You could go even further and use a type union (e.g. 'activitypub' | 'xmpp' | ...) instead of a plain string).

This enables IntelliSense to make concrete suggestions.

This would be acceptable if there's a way to clarify that the list is non-exhaustive. ActivityPub software names that are dynamically fetched are also accepted values

I see. Well, now you know. In case you run into some other place where it would be applicable.

Usually denoted with @param {*} proofData in JSDoc.

You often don't include this in other functions.

Removed all @async