reference docs for network Port API

[dckc]

What is the Problem Being Solved?

As a developer on the Agoric platform, I want to understand the network port API.

p.s. resolution: reference docs for @agoric/network package.

Description of the Design / Test Plan

As in the @agoric/network package README:

• Connecting to a Remote Port
• Opening a Listening Port and Accepting an Inbound Connection
• Sending Data
• Receiving Data
• Closing the Connection
• Removing a Listener
• Closing the Port Entirely

See also unit tests:

agoric-sdk/packages/vats$ yarn test test/network.test.js
  ✔ network - ibc (131ms)
    ℹ Opening a Listening Port
    ℹ Accepting an Inbound Connection
    ℹ Sending Data - echo
    ℹ Receiving Data hello198
    ℹ Closing the Connection
    ℹ Connecting to a Remote Port
    ℹ Sending Data - transfer
    ℹ Receiving Data inbound-msg

use the typedoc approach (#8720) and refine the source code until the generated docs are adequate.
The usual PR review process seems sufficient to judge adequacy of reference docs.

• url / publishing mechanics
  • cloudflare pages?

punted these from the critical path:

• Agoric/agoric.github.io#259
• quick ci for docs-only changes #9216

Security / Scaling / Upgrade Considerations

n/a

background

In reviewing a recent PR aimed at adding the network-vat in an upcoming release (#8721), I learned that the network vat -- the Port API at least -- is part of the developer API product. So it needs reference docs.

cc @sufyaankhan @michaelfig @iomekam @turadg

[dckc]

I broke ground: 035eafb

rendered: https://ag-api-docs-net.netlify.app/modules/_agoric_network.html
(manually deployed to netlify)

[dckc]

for stuff that's not part of the developer API product:

• @internal | TypeDoc

[dckc]

Generated docs for @agoric/network are available at https://agoric-sdk.pages.dev/modules/_agoric_network as part of #1032 .

And in changes such as ae0e43e , we seem to be keeping them up-to-date.
cc @0xpatrickdev @michaelfig @gibson042 @warner

I suppose this bit is outdated; doesn't do much harm, though:

<!--
  content should remain synchronized with
  https://github.com/Agoric/documentation/blob/main/main/reference/repl/networking.md
-->

Ideally, the example code in the README would be tested, but meanwhile, tests for open / initiate / send / close are in packages/vats/test/test-network.js. I added a bit of logging in 3d13c09 to make that explicit:

$ yarn test test/test-network.js 
...
  ✔ network - ibc
    ℹ Opening a Listening Port
    ℹ Accepting an Inbound Connection
    ℹ Sending Data - echo
    ℹ Receiving Data hello198
    ℹ Closing the Connection
    ℹ Connecting to a Remote Port
    ℹ Sending Data - transfer
    ℹ Receiving Data inbound-msg

We punted these from the critical path:

• Agoric/agoric.github.io#259
• quick ci for docs-only changes #9216