From 5724aa1d1b2f30296b134f1ee5de57e8f4737f34 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Mon, 10 Oct 2011 14:45:53 -0600 Subject: [PATCH] doc clarifications Merge to 5.2 --- collects/scribblings/foreign/cpointer.scrbl | 27 +++++++++++---------- collects/scribblings/reference/places.scrbl | 7 +++--- 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/collects/scribblings/foreign/cpointer.scrbl b/collects/scribblings/foreign/cpointer.scrbl index 5c40a00f4d..a6f072944f 100644 --- a/collects/scribblings/foreign/cpointer.scrbl +++ b/collects/scribblings/foreign/cpointer.scrbl @@ -22,20 +22,21 @@ to Racket, and accept only such tagged pointers when going to C. An optional @racket[ptr-type] can be given to be used as the base pointer type, instead of @racket[_pointer]. -By convention, tags are symbols named after the -type they point to. For example, the cpointer @racket[_car] would -be created using @racket['car] as the key. However, any symbol can be -used as the tag. -Pointer tags are checked with @racket[cpointer-has-tag?] and changed -with @racket[cpointer-push-tag!] which means that other tags are -preserved. Specifically, if a base @racket[ptr-type] is given and is -itself a @racket[_cpointer], then the new type will handle pointers -that have the new tag in addition to @racket[ptr-type]'s tag(s). When -the tag is a pair, its first value is used for printing, so the most -recently pushed tag which corresponds to the inheriting type will be -displayed. +Although any value can be used as a tag, by convention the symbol form +of a type name---without a leading underscore---is used as the +tag. For example, a pointer type @racketidfont{_animal} +would normally use @racket['animal] as the key. -@racket[_cpointer/null] is similar to @racket[_cpointer] except that +Pointer tags are checked with @racket[cpointer-has-tag?] and changed +with @racket[cpointer-push-tag!], which means that other tags are +preserved on an existing pointer value. Specifically, if a base +@racket[ptr-type] is given and is itself a @racket[_cpointer], then +the new type will handle pointers that have the new tag in addition to +@racket[ptr-type]'s tag(s). When the tag is a pair, its first value +is used for printing, so the most recently pushed tag which +corresponds to the inheriting type is displayed. + +The @racket[_cpointer/null] function is similar to @racket[_cpointer], except that it tolerates @cpp{NULL} pointers both going to C and back. Note that @cpp{NULL} pointers are represented as @racket[#f] in Racket, so they are not tagged.} diff --git a/collects/scribblings/reference/places.scrbl b/collects/scribblings/reference/places.scrbl index dffbb0d294..87980decf6 100644 --- a/collects/scribblings/reference/places.scrbl +++ b/collects/scribblings/reference/places.scrbl @@ -267,12 +267,13 @@ If any pumping threads were created to connect a non-@tech{file-stream } @defproc[(place-channel-get [pch place-channel?]) place-message-allowed?]{ - Returns a message received on channel @racket[pch]. + Returns a message received on channel @racket[pch], blocking until a + message is available. } -@defproc[(place-channel-put/get [pch place-channel?] [v any/c]) void]{ +@defproc[(place-channel-put/get [pch place-channel?] [v any/c]) any/c]{ Sends an immutable message @racket[v] on channel @racket[pch] and then - waits for a reply message on the same channel. + waits for a message (perhaps a reply) on the same channel. } @defproc[(place-message-allowed? [v any/c]) boolean?]{