Adding some comments documenting captp.js.

[cwebber]

First pass: there are some unanswered questions in the comments and some things are probably wrong!

I'd love review about how much I understand this... and I figured, while I'm trying to figure it out, maybe my attempt-at-understanding is generally useful for the module.

There are some questions (marked with ???) amongst the comments and some things are probably flat-out wrong, so review is encouraged before merging.

I'm happy to make some changes if you are willing to review... or if you'd prefer to just modify and pull in yourself, that's welcome too.

[cwebber]

Also I don't know anything about Agoric's style guide (or contemporary Javascript style at all) so sorry for the failing linting tests :)

[cwebber]

BTW, an additional thing to possibly comment, once understood:

<Zarutian_HTC> dustyweb: one thing I noticed about CTP_RETURN that the question gets deleted. No idea why.
<Zarutian_HTC> seem to prevent usage patterns like: const t1 = remoteObj~.x(); t1.y(); t1.z();
<dustyweb> Zarutian_HTC: yes that is curious
<dustyweb> Zarutian_HTC: mind if I put that on the issue tracker?
<Zarutian_HTC> sure
<dustyweb> Zarutian_HTC: I have a guess
<dustyweb> it's an attempt to prevent things from getting too out of hand before GC support in captp
<dustyweb> .js
<Zarutian_HTC> right
<Zarutian_HTC> the gc thing requires weakref and post mortem finalization

Are we right? :)

[michaelfig]

Are we right? :)

Probably! :)

BTW, your comments are welcome. You can look at the current CapTP as me trying to read and understand the Cap'n'Proto implementation and the liveSlots.js implementation, but not as well-documented.

[michaelfig]

Just a few changes. Thanks for this!

[cwebber]

Updated. Thank you!

(I don't completely understand why the directionality is introduced however... my read on the imports/exports and questions/answers per reading the original captp documentation is that the imports/exports end up being "specified" by the exporter and that questions/answers are "specified" by the questioner, and this is relevant to the way that collaborative GC ends up happening. But maybe I've misunderstood something... anyway, not critical to getting this PR in.)