Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

E reference docs lack example, link to narrative, appearance in IDE / LSP #2706

Open
dckc opened this issue Jan 30, 2025 · 0 comments
Open
Labels
bug Something isn't working documentation Improvements or additions to documentation

Comments

@dckc
Copy link
Contributor

dckc commented Jan 30, 2025

in progress; gotta to do a meeting

Describe the bug

When working on an example contract, I hovered over various bits of our API to check whether docs are adequate. E seems to be documented with an elaborate type but no prose / example / links:

Image

Steps to reproduce

  1. open packages/far/test/e.test.js in vs-code (or presumably any other editor based on the Language Server Protocol)
  2. hover over E
  3. see type info but no prose / example

Expected behavior

  1. At least these docs should show up:

/**
* 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.
*
* @template T
* @param {T} x target for method/function call
* @returns {ECallableOrMethods<RemoteFunctions<T>>} method/function call proxy
*/

Interestingly, they do show up in generated docs:

E | Endo API documentation

  1. The reference docs should cite narrative docs: Eventual Send with E()

  2. The reference docs should include an example, preferably one that's elaborated on in the narrative docs. E(x).method(...args) is a candidate, though not as

Platform environment

Additional context

Screenshots

@dckc dckc added bug Something isn't working documentation Improvements or additions to documentation labels Jan 30, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

1 participant