Add JSDoc for @cached

packages/@ember/-internals/metal/lib/cached.ts

@@ -4,7 +4,39 @@
 import { DEBUG } from '@glimmer/env';
 import { createCache, getValue } from '@glimmer/validator';
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+/**
+ * @decorator
+ *
+ * Memoizes the result of a getter based on autotracking.
+ *
+ * The `@cached` decorator can be used on native getters to memoize their return
+ * values based on the tracked state they consume while being calculated.
+ *
+ * By default a getter is always re-computed every time it is accessed. On
+ * average this is faster than caching every getter result by default.
+ *
+ * However, there are absolutely cases where getters are expensive, and their
+ * values are used repeatedly, so memoization would be very helpful.
+ * Strategic, opt-in memoization is a useful tool that helps developers
+ * optimize their apps when relevant, without adding extra overhead unless
+ * necessary.
+ *
+ * @example
+ *
+ * ```ts
+ * import { tracked, cached } from '@glimmer/tracking';
+ *
+ * class Person {
+ *   @tracked firstName = 'Jen';
+ *   @tracked lastName = 'Weber';
+ *
+ *   @cached
+ *   get fullName() {
+ *     return `${this.firstName} ${this.lastName}`;
+ *   }
+ * }
+ * ```
+ */
 export const cached: PropertyDecorator = (...args: any[]) => {
   const [target, key, descriptor] = args;