Improve annotation docs

JoinColony · Nov 14, 2022 · 9c8fd9a · 9c8fd9a
1 parent b984433
commit 9c8fd9a
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 8 deletions.
diff --git a/docs/api/classes/Colony.md b/docs/api/classes/Colony.md
@@ -55,17 +55,23 @@ This will annotate a transaction with an arbitrary text message. This only reall
 
 **`Remarks`**
 
-Requires an [IpfsAdapter](../interfaces/IpfsAdapter.md) that can upload and pin to IPFS. See its documentation for more information
+Requires an [IpfsAdapter](../interfaces/IpfsAdapter.md) that can upload and pin to IPFS. See its documentation for more information. Keep in mind that **the annotation itself is a transaction**.
 
 **`Example`**
 
 ```typescript
 // Immediately executing async function
 (async function() {
-  // Annotate a motion transaction to pay ourselves a little bonus :)
+
+  // Create a motion to pay 10 of the native token to some (maybe your own?) address
+  const [, { transactionHash }] = await colony.ext.motions.create.pay(
+    '0xb77D57F4959eAfA0339424b83FcFaf9c15407461',
+    w`10`,
+  );
+  // Annotate the motion transaction with a little explanation :)
   await colony.annotateTransaction(
-     '0xf1940d38e0a74262643a75b0f826353d62a505aedd9c95ae5fb5da6856e4adb2',
-        'I am creating this motion because I think I deserve a little bonus'
+     transactionHash,
+     'I am creating this motion because I think I deserve a little bonus'
   );
 })();
 ```

diff --git a/src/ColonyNetwork/Colony.ts b/src/ColonyNetwork/Colony.ts
@@ -487,16 +487,22 @@ export class Colony {
    *
    * This will annotate a transaction with an arbitrary text message. This only really works for transactions that happened within this Colony. This will upload the text string to IPFS and connect the transaction to the IPFS hash accordingly.
    *
-   * @remarks Requires an [[IpfsAdapter]] that can upload and pin to IPFS. See its documentation for more information
+   * @remarks Requires an [[IpfsAdapter]] that can upload and pin to IPFS. See its documentation for more information. Keep in mind that **the annotation itself is a transaction**.
    *
    * @example
    * ```typescript
    * // Immediately executing async function
    * (async function() {
-   *   // Annotate a motion transaction to pay ourselves a little bonus :)
+   *
+   *   // Create a motion to pay 10 of the native token to some (maybe your own?) address
+   *   const [, { transactionHash }] = await colony.ext.motions.create.pay(
+   *     '0xb77D57F4959eAfA0339424b83FcFaf9c15407461',
+   *     w`10`,
+   *   );
+   *   // Annotate the motion transaction with a little explanation :)
    *   await colony.annotateTransaction(
-   *      '0xf1940d38e0a74262643a75b0f826353d62a505aedd9c95ae5fb5da6856e4adb2',
-   *         'I am creating this motion because I think I deserve a little bonus'
+   *      transactionHash,
+   *      'I am creating this motion because I think I deserve a little bonus'
    *   );
    * })();
    * ```