fix: clarify TS Docs for better DX

Fixes #2936

packages/ts/react-signals/src/FullStackSignal.ts

@@ -14,7 +14,10 @@ interface VaadinGlobal {
 const ENDPOINT = 'SignalsHandler';
 
 /**
- * A return type for signal operations.
+ * A return type for signal operations that exposes a `result` property of type
+ * Promise, that resolves when the operation is completed. It allows defining
+ * callbacks to be run after the operation is completed, or error handling when
+ * the operation fails.
  */
 export type Operation = {
   result: Promise<void>;
@@ -230,7 +233,7 @@ export abstract class FullStackSignal<T> extends DependencyTrackingSignal<T> {
     }
   >();
 
-  // creates the obejct to be returned by operations to allow defining callbacks
+  // creates the object to be returned by operations to allow defining callbacks
   protected [$createOperation]({ id, promise }: { id?: string; promise?: Promise<void> }): Operation {
     const thens = this.#operationPromises;
     const promises: Array<Promise<void>> = [];

packages/ts/react-signals/src/ListSignal.ts

@@ -151,6 +151,7 @@ export class ListSignal<T> extends CollectionSignal<ReadonlyArray<ValueSignal<T>
   /**
    * Inserts a new value at the end of the list.
    * @param value - The value to insert.
+   * @returns An operation object that allows to perform additional actions.
    */
   insertLast(value: T): Operation {
     const event = createInsertLastStateEvent(value);
@@ -161,6 +162,7 @@ export class ListSignal<T> extends CollectionSignal<ReadonlyArray<ValueSignal<T>
   /**
    * Removes the given item from the list.
    * @param item - The item to remove.
+   * @returns An operation object that allows to perform additional actions.
    */
   remove(item: ValueSignal<T>): Operation {
     const entryToRemove = this.#values.get(item.id);

packages/ts/react-signals/src/ValueSignal.ts

@@ -44,6 +44,7 @@ export class ValueSignal<T> extends FullStackSignal<T> {
    * `replace` method instead.
    *
    * @param value - The new value.
+   * @returns An operation object that allows to perform additional actions.
    */
   set(value: T): Operation {
     const { parentClientSignalId } = this.server.config;
@@ -81,7 +82,8 @@ export class ValueSignal<T> extends FullStackSignal<T> {
    *
    * @param callback - The function that is applied on the current value to
    *                   produce the new value.
-   * @returns An operation object that allows to perform additional actions, including cancellation.
+   * @returns An operation object that allows to perform additional actions,
+   *                   including cancellation.
    */
   update(callback: (value: T) => T): OperationSubscription {
     const newValue = callback(this.value);