lib-hooks: document with comments

pkg/arvo/lib/pull-hook.hoon

@@ -1,3 +1,24 @@
+::  lib/pull-hook/hoon: helper for creating a push hook
+::  
+::   lib/pull-hook is a helper for automatically pulling data from a
+::   corresponding push-hook to a store. 
+::   
+::   ## Interfacing notes:
+::
+::   lib/push-hook provides the inner door with its own separate state.
+::   The inner door may interact with the library by producing cards or
+::   scrying. Do not pass any cards on a wire beginning with /helper as
+::   these wires are reserved by this library. Any watches/pokes/peeks
+::   not listed below will be routed to the inner door.
+::
+::   ##  Subscription paths
+::
+::   /tracking: The set of resources we are pulling
+::
+::   ##  Pokes
+::
+::   %pull-hook-action: Add/remove a resource from pulling.
+::
 /-  *pull-hook
 /+  default-agent, resource
 ::
@@ -5,13 +26,24 @@
 |%
 +$  card   card:agent:gall
 ::
+::  $config: configuration for the pull hook
+::
+::    .store-name: name of the store to proxy subscriptions to.
+::    .update-mark: mark that updates will be tagged with
+::    .push-hook-name: name of the corresponding push-hook
+
 +$  config
   $:  store-name=term
       update=mold
       update-mark=term
       push-hook-name=term
   ==
+::  
+::  $state-0: state for the pull hook
 ::
+::    .tracking: a map of resources we are pulling, and the ships that
+::    we are pulling them from.
+::    .inner-state: state given to internal door
 +$  state-0
   $:  %0
     tracking=(map resource ship)
@@ -37,7 +69,7 @@
   |*  config
   $_  ^|
   |_  bowl:gall
-  ::
+  ::  from agent:gall
   ++  on-init
     *[(list card) _^|(..on-init)]
   ::
@@ -77,7 +109,9 @@
     *[(list card) _^|(..on-init)]
   ::  +on-pull-nack: handle failed pull subscription
   ::
-  ::    This arm is called when a pull subscription fails.
+  ::    This arm is called when a pull subscription fails. lib/pull-hook
+  ::    will automatically delete the resource from .tracking by the
+  ::    time this arm is called.
   ::
   ++  on-pull-nack
     |~  [resource tang]

pkg/arvo/lib/push-hook.hoon

@@ -1,8 +1,42 @@
+::  lib/push-hook/hoon: helper for creating a push hook
+::  
+::   lib/push-hook is a helper for automatically pushing data from a
+::   local store to the corresponding pull-hook on remote ships. It also
+::   proxies remote pokes to the store.
+::
+::   ## Interfacing notes:
+::
+::   lib/push-hook provides the inner door with its own separate state.
+::   The inner door may interact with the library by producing cards or
+::   scrying. Do not pass any cards on a wire beginning with /helper as
+::   these wires are reserved by this library. Any watches/pokes/peeks
+::   not listed below will be routed to the inner door.
+::
+::   ##  Subscription paths
+::
+::   /resource/[resource]: Receive initial state and updates to
+::   .resource. .resource should be encoded with de-path:resource from
+::   /lib/resource. Facts on this path will be of mark
+::   update-mark.config
+::
+::   ##  Pokes
+::
+::   %push-hook-action: Add/remove a resource from pushing.
+::   [update-mark.config]: A poke to proxy to the local store
+::
 /-  *push-hook
 /+  default-agent, resource
 |%
 +$  card  card:agent:gall
 ::
+::  $config: configuration for the push hook
+::  
+::    .store-name: name of the store to proxy pokes and
+::    subscriptions to
+::    .store-path: subscription path to receive updates on
+::    .update-mark: mark that updates will be tagged with
+::    .pull-hook-name: name of the corresponding pull-hook
+::
 +$  config
   $:  store-name=term
       store-path=path
@@ -10,6 +44,12 @@
       update-mark=term
       pull-hook-name=term
   ==
+::
+::  $state-0: state for the push hook
+::
+::    .sharing: resources that the push hook is proxying
+::    .inner-state: state given to internal door
+::
 +$  state-0
   $:  %0
     sharing=(set resource)
@@ -20,6 +60,7 @@
   |*  =config
   $_  ^|
   |_  bowl:gall
+  ::  from agent:gall
   ::
   ++  on-init
     *[(list card) _^|(..on-init)]
@@ -58,14 +99,21 @@
   ++  on-fail
     |~  [term tang]
     *[(list card) _^|(..on-init)]
+  ::
   ::  +resource-for-update: get affected resource from an update
+  ::  
+  ::    Given a vase of the update, the mark of which is
+  ::    update-mark.config, produce the affected resource, if any.
+  ::
   ++  resource-for-update
     |~  vase
     *(unit resource)
   ::
   ::  +on-update: handle update from store
   ::
-  ::    Do extra stuff on store update
+  ::    Given an update from the store, do other things after proxying
+  ::    the update
+  ::
   ++  take-update
     |~  vase
     *[(list card) _^|(..on-init)]
@@ -81,7 +129,13 @@
   ::  +initial-watch: produce initial state for a subscription
   ::
   ::    .resource is the resource being subscribed to.
-  ::    .path is any additional information in the subscription wire
+  ::    .path is any additional information in the subscription wire.
+  ::    This would typically be used to encode state that the subscriber
+  ::    already has. For example, a chat client might encode
+  ::    the number of messages that it already has, or the date it last
+  ::    received an update.
+  ::
+  ::    If +initial-watch crashes, the subscription fails.
   ::
   ++  initial-watch
     |~  [path resource]