# Problem
`no-invalid-this` makes sure uses of `this` are valid (see [docs](https://eslint.org/docs/rules/no-invalid-this) and [implementation](8984c91372/lib/rules/utils/ast-utils.js (L900))). However, uses of `this` are rampant in our test suites because this is how mocha unit tests are structured, the Mocha context can be accessed only through `this`.
# Fix
So instead of disabling `no-invalid-this` in our test suites, this PR tags functions that reference `this` with `@this` and that satisfies the rule requirements (see [docs](https://eslint.org/docs/rules/no-invalid-this)).
# Discussion
It could be argued that this work just replaces one comment annotation with another so we did not really solve the underlying problem. However, the inherent problem lies in how mocha itself works and there is nothing we can do other than probably migrating to another framework that is more sane/type-safe. One minor improvement we get is we now have slightly less syntactic overhead because we need to tag just the function instead of individual lines in its body that violate the rule.
# Trade-offs
Pros:
- function tags are less than line tags
Cons:
- whitelisting one more tag with the tsdoc linter that our devs need to learn about
- still having rampant tags everywhere
Fixes https://github.com/Azure/azure-sdk-for-js/issues/11404
# Status quo
Some of our documentation comments are [TypeDoc](http://typedoc.org/guides/doccomments/) and some of them are JSDoc with type description in the comments even though it is for typed TS code.
# Standardization
I decided the best way to go about this is to migrate to [TSDoc](https://github.com/Microsoft/tsdoc) and enforcing it using the [tsdoc eslint plugin](https://www.npmjs.com/package/eslint-plugin-tsdoc).
Pros:
- TSDoc is a proposal to standardize the doc comments used in TypeScript code, so that different tools can extract content without getting confused by each other’s markup.
- It is being developed at Microsoft, with the TypeScript team.
- It has an ESLint plugin that enforces it and will error when it sees unsupported tags (e.g. `@memberof`, `@class`, `@constructor`, `@type`, etc).
Cons:
- It is still in early stages (adoption is ongoing though, e.g. it is being used by the API extractor tool).
- TSDoc != TypeDoc (the tool we currently use for generating our documentation). However, TypeDoc plans to officially support TSDoc in v1.1 (see https://github.com/TypeStrong/typedoc/issues/1266).
# Notable tag changes
- `@ignore` is a JSDoc tag and was used in conjunction with `@internal`. These tags were needed because [TypeDoc does not yet support documenting only definitions exported by the entry point](https://github.com/TypeStrong/typedoc/pull/1184#issuecomment-650809143) and still documents everything exported from all files. I removed `@ignore` because [`@internal`](https://tsdoc.org/pages/tags/internal) only should suffice
- `@ignore` when used alone is replaced with TypeDoc's [`hidden`](http://typedoc.org/guides/doccomments/#hidden-and-ignore). EDIT: I replaced `@ignore` with [`@hidden`](https://github.com/TypeStrong/typedoc/releases/tag/v0.12.0) because the TypeDoc version used for `docs.microsoft.com` is v0.15.0 which does not support `--stripInternal`. After, they upgrade, I will remove all `@hidden` tags.
- `@summary` is gone because it is not part of TSDoc or TypeDoc
This PR applies the changes to packages that respect our linting rules. Ones that do not yet will be migrated later when we start fixing their linting issues.
Here are vanilla examples of TypeDoc 0.18.0 (version used by our EngSys) after the changes here as a sanity check:
- random method:
- a class constructor that used to have type information in the documentation comments:
# `@hidden` works the same way as `@ignore`
Here are the list of documented functions generated by `TypeDoc v0.15.0` for the text analytics package and there is no function that was marked `@hidden`, e.g. `combineSuccessfulAndErroneousDocumentsWithStatisticsAndModelVersion`
# Things to consider
- Our documentation must be generated using the TypeDoc flag [`--stripInternal`](http://typedoc.org/guides/options/#stripinternal)
- Should we add a `docs` npm script to our `package.json`s (similar to [Cosmos's](2424b74f02/sdk/cosmosdb/cosmos/package.json (L60))) so that we can see how our docs are generated as we write our comments?
Fixes https://github.com/Azure/azure-sdk-for-js/issues/3027.
Deyaaeldeen Almahallawi
