Merge pull request #947 from NullVoxPopuli/update-docs

Update function-based resource in-editor docs

Author: NullVoxPopuli

.changeset/nine-hairs-cry.md

@@ -0,0 +1,5 @@
+---
+"ember-resources": patch
+---
+
+Update in-editor docs on the function resource

ember-resources/src/core/class-based/resource.ts

@@ -51,6 +51,17 @@ declare const __ResourceArgs__: unique symbol;
  * which requires that the "State machine interpreter"
  * is stopped when you are discarding the parent context (such as a component).
  *
+ * _When would you reach for the class-based `Resource` instead of the function-based `resource`?_
+ *
+ *  - the capabilities of the function-based resource and class-based resource are almost identical.
+ *    the main difference is that function-based resources may represent a single a value
+ *    (which could, itself, be a class instance, or object with properties),
+ *    class-based-resources expose the whole class instance to the consumer.
+ *
+ *  - function-based resources, however, are much easier to work with and understand, and have
+ *    better intellisense capabilities.
+ *
+ *
  * An example
  * ```js
  * import { Resource } from 'ember-resources';

ember-resources/src/core/function-based/resource.ts

@@ -9,8 +9,7 @@ import { wrapForPlainUsage } from './utils';
 import type { InternalFunctionResourceConfig, ResourceFn, ResourceFunction } from './types';
 
 /**
- * `resource` is an alternative API to the class-based `Resource`.
- * It may provide a single read-only value and provides a way to optionally cleanup.
+ * `resource` provides a single reactive read-only value with lifetime and may have cleanup.
  *
  * Arguments passed to the `resource` function:
  * ```js
@@ -31,15 +30,6 @@ import type { InternalFunctionResourceConfig, ResourceFn, ResourceFunction } fro
  *  );
  *  ```
  *
- * When would you reach for the class-based `Resource`?
- *  - the capabilities of the function-based resource and class-based resource are identical,
- *    with the exception that function-based resources may represent a single value, rather than
- *    an object with properties/methods (the only option with class-based resources)
- *
- * A function-resource
- *  - _must_ return a value.
- *  - cannot, itself, be async - but can interact with promises and update a value
- *
  *  Example using `fetch` + `AbortController`
  *  ```js
  *  import { use, resource } from 'ember-resources';
@@ -80,7 +70,8 @@ import type { InternalFunctionResourceConfig, ResourceFn, ResourceFunction } fro
  *
  *
  *  Example using strict mode + `<template>` syntax and a template-only component:
- *  ```jsx gjs
+ *
+ *  ```js
  *  import { resource } from 'ember-resources';
  *  import { TrackedObject } from 'tracked-built-ins';
  *