From b60f841de9cc8d0f7019d3dfeda87b1240f8ff99 Mon Sep 17 00:00:00 2001
From: Chris Hibbert <hibbert@agoric.com>
Date: Wed, 5 Feb 2025 14:07:28 -0800
Subject: [PATCH] docs: add some javadoc on E in hopes that it'll be visible in
 IDEs

---
 packages/eventual-send/src/E.js       |  8 ++++++++
 packages/eventual-send/src/no-shim.js | 11 +++++++++++
 2 files changed, 19 insertions(+)

diff --git a/packages/eventual-send/src/E.js b/packages/eventual-send/src/E.js
index d92d61135d..88309686e1 100644
--- a/packages/eventual-send/src/E.js
+++ b/packages/eventual-send/src/E.js
@@ -195,6 +195,14 @@ const makeE = HandledPromise => {
        * method calls returns a promise. The method will be invoked on whatever
        * 'x' designates (or resolves to) in a future turn, not this one.
        *
+       * An example call would be
+       *
+       * E(zoe).install(bundle)
+       *   .then(installationHandle => { ... })
+       *   .catch(err => { ... });
+       *
+       *  See https://endojs.github.io/endo/functions/_endo_far.E.html for details.
+       *
        * @template T
        * @param {T} x target for method/function call
        * @returns {ECallableOrMethods<RemoteFunctions<T>>} method/function call proxy
diff --git a/packages/eventual-send/src/no-shim.js b/packages/eventual-send/src/no-shim.js
index 387d001271..402e92ff5f 100644
--- a/packages/eventual-send/src/no-shim.js
+++ b/packages/eventual-send/src/no-shim.js
@@ -5,6 +5,17 @@ import makeE from './E.js';
 /** @import {ECallableOrMethods, EGetters, ERef, ERemoteFunctions, ESendOnlyCallableOrMethods, LocalRecord, RemoteFunctions} from './E.js' */
 
 const hp = HandledPromise;
+
+/**
+ * E(x) returns a proxy on which you can call arbitrary methods. Each of these method calls returns a promise.
+ * The method will be invoked on whatever 'x' designates (or resolves to) in a future turn, not this one.
+ *
+ * E.get(x) returns a proxy on which you can get arbitrary properties. Each of these properties returns a
+ * promise for the property.  The promise value will be the property fetched from whatever 'x' designates (or
+ * resolves to) in a future turn, not this one.
+ *
+ * E.when(x, res, rej) is equivalent to HandledPromise.resolve(x).then(res, rej)
+ */
 export const E = makeE(hp);
 export { hp as HandledPromise };