done with documentation from accept_message to candid_encode besides …

…call

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 (

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 (

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) {

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 (

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 (