question because Im curious: Do you think using the callback tag for function parameters would be suitable?

Is this meant to be object? I'm also having trouble understanding the difference between the lowercase and uppercase uses for jsdocs (in general). For example in the params doc page, we use uppercase Object rather than lowercase. But I'm seeing both existing in searchfox: https://searchfox.org/mozilla-central/search?q=%7Bobject&path=&case=false&regexp=false.

nitpick: We could also add a private tag.

nitpick: This means an array of MigrationResources right? Just wanted to make sure since we seem to be using both [] and Array<...> to indicate arrays. We could make them consistent if we wanted to.

Yep! But I'll file this as a follow-up. I mainly wanted to write this patch to get the minimum changes in the tree to enable these rules. We can start to improve the documentation afterwards (and ensure we're following the JSDoc requirements while we do it! :) )

Filed follow-up as: https://bugzilla.mozilla.org/show_bug.cgi?id=1802979

Ooof, yep, that's supposed to be object. Good eye, thanks!

Looks like casing is governed by this ESLint rule: https://github.com/gajus/eslint-plugin-jsdoc/blob/master/.README/rules/check-types.md

I think we use [] when we want to indicate a homogeneous collection - ie, an array that only contains MigrationResource's in this case.

For * @returns {Promise<Array<Array>>} for the promiseMigration helper, it's a little tricker, because that's an array of arrays. I'm not sure how to represent that with the [] syntax. Maybe this?

* @returns {Promise<Array<string[]>>}

I've filed bug 1802978 to update the existing documentation to use more consistent array types.