document place termination better

e.g., the fact that the exit handler is set in a place

collects/scribblings/reference/evts.scrbl

@@ -183,17 +183,13 @@ generate events (see @racket[prop:evt]).
    or blocked on events with timeouts that have not yet expired. The
    event's result is @|void-const|.}
 
- @item{@racket[place-channel] --- a place-channel is ready when
+ @item{@racket[_place-channel] --- a @tech{place channel} is ready when
  @racket[place-channel-get] would not block. The channel's result as an
  event is the same as the @racket[place-channel-get] result.}
 
- @item{@racket[place] --- a place is ready when @racket[place-channel-get]
- would not block. The result as an event is the same as the
- @racket[place-channel-get] result.}
-
  @item{@racket[_place-dead] --- an event returned by
- @racket[place-dead-evt] applied to @racket[p] is ready when
+ @racket[(place-dead-evt _p)] is ready when @racket[_p] has
- @racket[p] has terminated.  @ResultItself[_place-dead].}
+ terminated.  @ResultItself[_place-dead].}
 
  ]
 

collects/scribblings/reference/places.scrbl

@@ -57,7 +57,7 @@ separate places. At the same time, the setup and communication costs
 for places can be higher than for futures.
 
 For example, the following expression lanches two places, echoes a
-message to each, and then waits for the places to complete and return:
+message to each, and then waits for the places to terminate:
 
 @racketblock[
 (let ([pls (for/list ([i (in-range 2)])
@@ -117,7 +117,20 @@ are simulated using @racket[thread].}
  with the name @racket[start-proc]. The function must accept a single
  argument, which is a @tech{place channel} that corresponds to the
  other end of communication for the @tech{place descriptor} returned
- by @racket[place].}
+ by @racket[place].
+
+ When the @tech{place} is created, the initial @tech{exit handler}
+ terminates the place, using the argument to the exit handler as the
+ place's @deftech{completion value}. Use @racket[(exit _v)] to
+ immediately terminate a place with the completion value
+ @racket[_v]. Since a completion value is limited to an exact integer
+ between @racket[0] and @racket[255], any other value for @racket[v]
+ is converted to @racket[0].
+
+ If the function indicated by @racket[module-path] and
+ @racket[start-proc] returns, then the place terminates with the
+ @tech{completion value} @racket[0].}
+
 
 @defform[(place id body ...+)]{
   Creates a place that evaluates @racket[body]
@@ -131,17 +144,27 @@ are simulated using @racket[thread].}
 
 
 @defproc[(place-wait [p place?]) exact-integer?]{
-  Returns the completion value of the place indicated by @racket[p],
+  Returns the @tech{completion value} of the place indicated by @racket[p],
-  blocking until the place completes if it has not already completed.
+  blocking until the place has terminated.
 }
 
+
+@defproc[(place-dead-evt [p place?]) evt?]{
+
+Returns a @tech{synchronizable event} (see @secref["sync"]) that is
+ready if and only if @racket[p] has terminated.}
+
+
+@defproc[(place-kill [p place?]) void?]{
+  Immediately terminates the place, setting the place's
+  @tech{completion value} to @racket[1] if the place does not have a
+  completion value already.}
+
+
 @defproc[(place-break [p place?]) void?]{
   Sends place @racket[p] a break signal; see @secref["breakhandler"].
 }
 
-@defproc[(place-kill [p place?]) void?]{
-  Terminates the place indicated by @racket[p],
-}
 
 @defproc[(place-channel) (values place-channel? place-channel?)]{
 
@@ -210,13 +233,3 @@ messages:
 ]}
 
 @;------------------------------------------------------------------------
-@;@section[#:tag "placesync"]{Synchronizing Places}
-
-@defproc[(place-dead-evt [p place?]) evt?]{
-
-Returns a @tech{synchronizable event} (see @secref["sync"]) that is
-ready if and only if @racket[p] has terminated.
-
-}
-
-@;------------------------------------------------------------------------