invite: add comments and clean up

pkg/arvo/app/invite-store.hoon

@@ -92,21 +92,11 @@
   ^-  (quip move _this)
   ?>  (team:title our.bol src.bol)
   ?-  -.action
-      %create
-    (handle-create action)
-  ::
-      %delete
-    (handle-delete action)
-  ::
-      %invite
-    (handle-invite action)
-  ::
-      %accept
-    (handle-accept action)
-  ::
-      %decline
-    (handle-decline action)
-  ::
+      %create   (handle-create action)
+      %delete   (handle-delete action)
+      %invite   (handle-invite action)
+      %accept   (handle-accept action)
+      %decline  (handle-decline action)
   ==
 ::
 ++  handle-create

pkg/arvo/lib/invite-json.hoon

@@ -32,10 +32,10 @@
   ^-  json
   =,  enjs:format
   %-  pairs
-  :~  [%path (path path.invite)]
-      [%ship (ship ship.invite)]
-      [%recipient (ship recipient.invite)]
+  :~  [%ship (ship ship.invite)]
       [%app [%s app.invite]]
+      [%path (path path.invite)]
+      [%recipient (ship recipient.invite)]
       [%text [%s text.invite]]
   ==
 ::
@@ -127,10 +127,10 @@
   ::
   ++  invi
     %-  ot
-    :~  [%path pa]
-        [%ship (su ;~(pfix sig fed:ag))]
-        [%recipient (su ;~(pfix sig fed:ag))]
+    :~  [%ship (su ;~(pfix sig fed:ag))]
         [%app (se %tas)]
+        [%path pa]
+        [%recipient (su ;~(pfix sig fed:ag))]
         [%text so]
     ==
   --

pkg/arvo/sur/invite-store.hoon

@@ -2,33 +2,38 @@
 ++  serial  @uvH
 ::
 +$  invite
-  $:  =path
-      =ship
-      recipient=ship
-      app=@tas
-      text=cord
+  $:  =ship           ::  ship to subscribe to upon accepting invite
+      app=@tas        ::  app to subscribe to upon accepting invite
+      =path           ::  path to subscribe to upon accepting invite
+      recipient=ship  ::  recipient to receive invite
+      text=cord       ::  text to describe the invite
   ==
 ::
+::  +invites: each application using invites creates its own path that
+::  contains a map of serial to invite. this allows it to only receive
+::  invites that it is concerned with
+::
++$  invites  (map path invitatory)   ::  main data structure
+::
 +$  invitatory  (map serial invite)  ::  containing or conveying an invitation
 ::
-+$  invites  (map path invitatory)
 ::
 +$  invite-base
-  $%  [%create =path]
-      [%delete =path]
-      [%invite =path uid=serial =invite]
-      [%decline =path uid=serial]
+  $%  [%create =path]                       ::  create a path
+      [%delete =path]                       ::  delete a path
+      [%invite =path uid=serial =invite]    ::  receive an invite at path/uid
+      [%decline =path uid=serial]           ::  decline an invite at path/uid
   ==
 ::
 +$  invite-action
   $%  invite-base
-      [%accept =path uid=serial]
+      [%accept =path uid=serial]            ::  accept an invite at path/uid
   ==
 ::
 +$  invite-update
   $%  invite-base
-      [%invitatory =invitatory]
-      [%accepted =path uid=serial =invite]
+      [%invitatory =invitatory]             ::  receive invitatory
+      [%accepted =path uid=serial =invite]  ::  an invite has been accepted
   ==
 --