From 667cd3a1d4ae44b494a730f8f4b06efb6c9f4ae5 Mon Sep 17 00:00:00 2001
From: Jordan Last <jordan.michael.last@gmail.com>
Date: Mon, 13 Jan 2025 10:40:15 -0700
Subject: [PATCH] done with documentation from accept_message to candid_encode
 besides call

---
 src/lib/stable/ic_apis/accept_message.ts | 11 ++++++-----
 src/lib/stable/ic_apis/arg_data_raw.ts   | 25 ++++++++++++------------
 src/lib/stable/ic_apis/caller.ts         | 20 +++++++++++--------
 src/lib/stable/ic_apis/candid_decode.ts  |  9 +++++----
 src/lib/stable/ic_apis/candid_encode.ts  |  9 +++++----
 5 files changed, 41 insertions(+), 33 deletions(-)

diff --git a/src/lib/stable/ic_apis/accept_message.ts b/src/lib/stable/ic_apis/accept_message.ts
index 97b9afc93b..0c547e0161 100644
--- a/src/lib/stable/ic_apis/accept_message.ts
+++ b/src/lib/stable/ic_apis/accept_message.ts
@@ -1,14 +1,15 @@
 /**
  * Accepts an ingress message during message inspection.
  *
- * @returns void, or no effect if called outside the IC environment
+ * @returns void
  *
  * @remarks
- * - Signals that a message should proceed to execution
+ *
+ * - Traps if invoked twice
  * - **Call Context**:
- *   - inspectMessage
- * - **When called outside of Call Context**:
- *   - Traps
+ *   - \@inspectMessage
+ * - **Outside of Call Context**:
+ *   - traps
  */
 export function acceptMessage(): void {
     if (
diff --git a/src/lib/stable/ic_apis/arg_data_raw.ts b/src/lib/stable/ic_apis/arg_data_raw.ts
index b83772d8af..c8a9ca01e7 100644
--- a/src/lib/stable/ic_apis/arg_data_raw.ts
+++ b/src/lib/stable/ic_apis/arg_data_raw.ts
@@ -1,20 +1,21 @@
 /**
- * Returns the raw argument data passed to the current method call.
+ * Returns the argument data of the current method call as bytes.
  *
- * @returns The raw argument bytes as Uint8Array, or empty array if called outside the IC environment
+ * @returns The argument bytes
  *
  * @remarks
+ *
  * - **Call Context**:
- *   - init
- *   - postUpgrade
- *   - update
- *   - query (replicated and non-replicated)
- *   - composite query
- *   - after a cross-canister call
- *   - after a cross-canister call from a composite query
- *   - inspectMessage
- * - **When called outside of Call Context**:
- *   - Traps
+ *   - \@init
+ *   - \@postUpgrade
+ *   - \@inspectMessage
+ *   - \@update
+ *   - \@query, replicated and non-replicated
+ *   - \@query(..., { composite: true })
+ *   - after a successful cross-canister await
+ *   - after a successful cross-canister await from a composite query
+ * - **Outside of Call Context**:
+ *   - traps
  */
 export function argDataRaw(): Uint8Array {
     if (
diff --git a/src/lib/stable/ic_apis/caller.ts b/src/lib/stable/ic_apis/caller.ts
index bc942fd995..9621851ec9 100644
--- a/src/lib/stable/ic_apis/caller.ts
+++ b/src/lib/stable/ic_apis/caller.ts
@@ -1,24 +1,28 @@
 import { Principal } from '@dfinity/principal';
 
 /**
- * Returns the {@link Principal} of the identity that called the current method.
+ * Returns the Principal of the identity that initiated the current call.
  *
- * @returns The caller's Principal, or the anonymous Principal if called outside the IC environment
+ * @returns The caller's Principal
  *
  * @remarks
- * - Returns the immediate caller's Principal
- *   - For inter-canister calls, returns the calling canister's Principal
- *   - For user calls, returns the user's Principal
- *   - For anonymous calls, returns the anonymous Principal
+ *
+ * When called from:
+ * - \@init: Principal of the identity requesting installation
+ * - \@postUpgrade: Principal of the identity requesting upgrade
+ * - \@heartbeat: Principal of the management canister
+ * - timer: Principal of the management canister
+ * - inter-canister callee: Principal of the calling canister
+ *
  * - **Call Context**:
- *   - Any method (not start)
+ *   - any besides start
  */
 export function caller(): Principal {
     if (
         globalThis._azleIcStable === undefined &&
         globalThis._azleIcExperimental === undefined
     ) {
-        return Principal.fromHex('04');
+        return Principal.fromHex('04'); // the anonymous principal
     }
 
     if (globalThis._azleIcExperimental !== undefined) {
diff --git a/src/lib/stable/ic_apis/candid_decode.ts b/src/lib/stable/ic_apis/candid_decode.ts
index fcf40b94ee..d6fda1e831 100644
--- a/src/lib/stable/ic_apis/candid_decode.ts
+++ b/src/lib/stable/ic_apis/candid_decode.ts
@@ -1,12 +1,13 @@
 /**
- * Converts binary Candid data into its string representation.
+ * Decodes binary Candid value bytes into its string representation.
  *
- * @param candidBytes - The binary Candid data to decode
- * @returns The decoded Candid type string, or empty string if called outside the IC environment
+ * @param candidBytes - The binary Candid value bytes to decode
+ * @returns The decoded Candid value string
  *
  * @remarks
+ *
  * - **Call Context**:
- *   - Any method
+ *   - any
  */
 export function candidDecode(candidBytes: Uint8Array): string {
     if (
diff --git a/src/lib/stable/ic_apis/candid_encode.ts b/src/lib/stable/ic_apis/candid_encode.ts
index 1d13bd4429..77e384158c 100644
--- a/src/lib/stable/ic_apis/candid_encode.ts
+++ b/src/lib/stable/ic_apis/candid_encode.ts
@@ -1,12 +1,13 @@
 /**
- * Converts a Candid string into its binary representation.
+ * Converts a Candid value string into its binary representation.
  *
- * @param candidString - A valid Candid type string (e.g. "(nat8,bool)")
- * @returns The binary encoding as a Uint8Array, or empty array if called outside the IC environment
+ * @param candidString - A Candid value string
+ * @returns The encoded binary Candid value bytes
  *
  * @remarks
+ *
  * - **Call Context**:
- *   - Any method
+ *   - any
  */
 export function candidEncode(candidString: string): Uint8Array {
     if (