From 0b0aabfbfd301ba040f8bf5b6b218ff5520232c5 Mon Sep 17 00:00:00 2001
From: Tony Garnock-Jones <tonygarnockjones@gmail.com>
Date: Fri, 26 Apr 2013 18:22:14 -0400
Subject: [PATCH] Yet more documentation.

---
 marketplace/scribblings/highlevel.scrbl | 28 ++++++++-----
 marketplace/scribblings/lowlevel.scrbl  | 52 ++++++++++++++++++++++---
 2 files changed, 66 insertions(+), 14 deletions(-)

diff --git a/marketplace/scribblings/highlevel.scrbl b/marketplace/scribblings/highlevel.scrbl
index d4dcd61..3d9796b 100644
--- a/marketplace/scribblings/highlevel.scrbl
+++ b/marketplace/scribblings/highlevel.scrbl
@@ -2,8 +2,21 @@
 @require[racket/include]
 @include{prelude.inc}
 
+@require[(for-label (except-in "../sugar-untyped.rkt"
+			       transition/no-state)
+		    (only-in "../drivers/tcp-bare.rkt" tcp)
+		    (except-in "../sugar-typed.rkt"
+			       ?))]
+
 @title[#:tag "high-level-interface"]{High-level interface}
 
+This high-level interface between a VM and a process is analogous to
+the @emph{C library interface} of a Unix-like operating system. The
+@secref{low-level-interface} corresponds to the @emph{system call
+interface} of a Unix-like operating system.
+
+@section{Using @tt{#lang marketplace} and friends}
+
 @defmodulelang*[(marketplace
 		 marketplace/flow-control
 		 marketplace/typed
@@ -36,11 +49,6 @@ There are a handful of variant languages to choose from:
 
 ]
 
-This high-level interface between a VM and a process is analogous to
-the @emph{C library interface} of a Unix-like operating system. The
-@secref{low-level-interface} corresponds to the @emph{system call
-interface} of a Unix-like operating system.
-
 @section{Using Marketplace as a library}
 
 @defmodule*[(marketplace/sugar-untyped
@@ -90,10 +98,12 @@ its state type).
 
 @section{Constructing topics and roles}
 
-**** ?
-**** Role
-**** Orientation
-**** InterestType
+As previously mentioned, @tech{topics} are ordinary Racket values
+which may have embedded wildcards. The identifier @racket[?] produces
+a fresh wildcard value for use in topic patterns.
+
+For example,
+TODO
 
 @section{Constructing transitions}
 **** transition, transition:, transition/no-state
diff --git a/marketplace/scribblings/lowlevel.scrbl b/marketplace/scribblings/lowlevel.scrbl
index 3890784..e7f9b5b 100644
--- a/marketplace/scribblings/lowlevel.scrbl
+++ b/marketplace/scribblings/lowlevel.scrbl
@@ -41,6 +41,48 @@ Typed Racket types capturing various notions of handler function.
 
 }
 
+@section{Topics and Roles}
+
+@deftype[Topic Any]{
+
+As previously mentioned, @tech{topics} are ordinary Racket values
+which may have embedded wildcards.
+
+}
+
+@defthing[? Topic]{
+
+Each time @racket[?] is used in an expression context, it produces a
+fresh topic wildcard, suitable for use in a topic pattern.
+
+}
+
+@deftogether[(
+@defstruct*[role ([orientation Orientation] [topic Topic] [interest-type InterestType]) #:prefab]
+@deftype[Role role]
+)]{
+
+Roles are almost always constructed by the
+@racket[endpoint]/@racket[endpoint:] macros or by the VM
+implementations themselves. User programs generally only need to
+destructure @racket[role] instances.
+
+TODO: Role
+
+}
+
+@deftype[Orientation (U 'publisher 'subscriber)]{
+
+TODO: Orientation
+
+}
+
+@deftype[InterestType (U 'participant 'observer 'everything)]{
+
+TODO: InterestType
+
+}
+
 @section{Endpoint Events}
 
 @deftogether[(
@@ -209,11 +251,11 @@ approach.
 @deftype[Quit quit]
 )]{
 
-Kills a sibling.@note{Or, if @racket[at-meta-level], a sibling of the
-containing VM.} If @racket[quit-pid] is @racket[#f], kills the current
-process; otherwise, kills the process with the given PID. The
-@racket[quit-reason] is passed on to peers of currently-active
-endpoints in the process to be killed, as part of a
+Kills a sibling process.@note{Or, if @racket[at-meta-level], a sibling
+process of the containing VM.} If @racket[quit-pid] is @racket[#f],
+kills the current process; otherwise, kills the process with the given
+PID. The @racket[quit-reason] is passed on to peers of
+currently-active endpoints in the process to be killed, as part of a
 @racket[absence-event], just as if each active endpoint were deleted
 manually before the process exited.