From 8e2b9d72e5f9500429905e07ea8a0f96510457e4 Mon Sep 17 00:00:00 2001 From: Tony Garnock-Jones Date: Wed, 29 May 2013 17:23:52 -0400 Subject: [PATCH] Fixup documentation internal linking. --- marketplace/scribblings/concepts.scrbl | 4 +- marketplace/scribblings/drivers.scrbl | 9 ++++ marketplace/scribblings/from.rkt | 12 +++++ marketplace/scribblings/highlevel.scrbl | 30 ++++++++---- marketplace/scribblings/lowlevel.scrbl | 49 +++++++++++++------ .../management-and-monitoring.scrbl | 7 +++ marketplace/scribblings/prelude.inc | 6 +++ 7 files changed, 92 insertions(+), 25 deletions(-) create mode 100644 marketplace/scribblings/from.rkt diff --git a/marketplace/scribblings/concepts.scrbl b/marketplace/scribblings/concepts.scrbl index fc80cc1..9795afd 100644 --- a/marketplace/scribblings/concepts.scrbl +++ b/marketplace/scribblings/concepts.scrbl @@ -67,7 +67,7 @@ handler, then, has the following approximate type: @centered{@italic{State} × @italic{Event} → @italic{State} × (Listof @italic{Action})} Event handlers are registered with the VM by creating @tech{endpoints} -using the @racket[endpoint] macro (described in @secref{Actions}) or +using the @racket[endpoint] macro (described in @secref{endpoint-dsl}) or the low-level @racket[add-endpoint] structure (described in @secref{endpoints-and-messages}). @@ -141,6 +141,8 @@ Roles have three parts: @section[#:tag "messages-and-topics"]{Messages and Topics} +@declare-exporting[marketplace] + @deftech{Messages} are simply Racket data structures. They can be any value for which @racket[equal?] is defined, any @racket[#:prefab] structure, most @racket[#:transparent] structures, or any non-object diff --git a/marketplace/scribblings/drivers.scrbl b/marketplace/scribblings/drivers.scrbl index e008891..5478548 100644 --- a/marketplace/scribblings/drivers.scrbl +++ b/marketplace/scribblings/drivers.scrbl @@ -2,6 +2,9 @@ @require[racket/include] @include{prelude.inc} +@require[(for-label marketplace/drivers/event-relay + marketplace/drivers/tcp-bare)] + @title{Drivers} @section{event-relay} @@ -44,6 +47,12 @@ with a running @racket[event-relay]. } +@defthing[tcp Spawn]{ + +A pre-made @racket[spawn] action equivalent to @racket[(tcp-driver)]. + +} + } @subsection{TCP channels} diff --git a/marketplace/scribblings/from.rkt b/marketplace/scribblings/from.rkt new file mode 100644 index 0000000..8ae90d6 --- /dev/null +++ b/marketplace/scribblings/from.rkt @@ -0,0 +1,12 @@ +#lang racket/base +;; Provides |from|, useful for importing identifiers from non-default +;; contexts without spelling them differently. + +(require scribble/decode) + +(provide from) + +(define-syntax-rule (from require-spec pre-content ...) + (let () + (local-require require-spec) + (splice (list pre-content ...)))) diff --git a/marketplace/scribblings/highlevel.scrbl b/marketplace/scribblings/highlevel.scrbl index c51b31f..38055c6 100644 --- a/marketplace/scribblings/highlevel.scrbl +++ b/marketplace/scribblings/highlevel.scrbl @@ -2,14 +2,16 @@ @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" - ?))] +@require[(for-label (except-in marketplace/sugar-untyped transition/no-state) + (only-in marketplace/drivers/tcp-bare tcp) + (except-in marketplace/sugar-typed ?))] @title[#:tag "high-level-interface"]{High-level interface} +@declare-exporting[#:use-sources (marketplace/sugar-values + marketplace/sugar-untyped + marketplace/sugar-typed)] + 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 @@ -63,7 +65,10 @@ and @racket[ground-vm:] explicitly. @section{Using Marketplace as a library} @defmodule*[(marketplace/sugar-untyped - marketplace/sugar-typed)] + marketplace/sugar-typed) + #:use-sources (marketplace/sugar-values + marketplace/sugar-untyped + marketplace/sugar-typed)] Instead of using Racket's @tt{#lang} feature, ordinary Racket programs can use Marketplace features by requiring Marketplace modules @@ -109,6 +114,11 @@ its state type). @section[#:tag "constructing-transitions"]{Constructing transitions} +@declare-exporting[#:use-sources (marketplace + marketplace/sugar-values + marketplace/sugar-untyped + marketplace/sugar-typed)] + @deftogether[( @defform[(transition new-state action-tree ...)] @defform[(transition: new-state : State action-tree ...)] @@ -484,10 +494,10 @@ to the orientation of the current endpoint) or @defproc[(delete-endpoint [id Any] [reason Any #f]) Action]{ Use this action to delete a previously-added endpoint by name. The -@racket[delete-endpoint-id] must be @racket[equal?] to the -corresponding @racket[add-endpoint-pre-eid]; when @racket[endpoint] -was used to construct the endpoint to be deleted, the relevant name is -that bound by @racket[#:let-name] or supplied to @racket[#:name]. See +@racket[id] given must be @racket[equal?] to the corresponding +@racket[add-endpoint-pre-eid]; when @racket[endpoint] was used to +construct the endpoint to be deleted, the relevant name is that bound +by @racket[#:let-name] or supplied to @racket[#:name]. See @secref{naming-endpoints}. If @racket[reason] is supplied, it is included in the corresponding diff --git a/marketplace/scribblings/lowlevel.scrbl b/marketplace/scribblings/lowlevel.scrbl index 1a2aad7..4d575f0 100644 --- a/marketplace/scribblings/lowlevel.scrbl +++ b/marketplace/scribblings/lowlevel.scrbl @@ -2,8 +2,6 @@ @require[racket/include] @include{prelude.inc} -@require[(for-label "../main.rkt")] - @title[#:tag "low-level-interface"]{Low-level interface} @defmodule[marketplace] @@ -41,19 +39,30 @@ Typed Racket types capturing various notions of handler function. } -@section{Topics and Roles} +@section{Messages, Topics and Roles} -@deftype[Topic Any]{ +@declare-exporting[marketplace marketplace/sugar-untyped marketplace/sugar-typed + #:use-sources (marketplace marketplace/sugar-untyped marketplace/sugar-typed)] -As previously mentioned, @tech{topics} are ordinary Racket values -which may have embedded wildcards. +@deftogether[( +@deftype[Message Any] +@deftype[Topic Any] +)]{ + +As previously mentioned, @tech{messages} are ordinary Racket values, +and @tech{topics} are ordinary Racket values which may have embedded +wildcards. } -@defthing[? Topic]{ +@deftogether[( +@defproc[(wild) Topic] +@defthing[#:kind "syntax" ? Topic] +)]{ -Each time @racket[?] is used in an expression context, it produces a -fresh topic wildcard, suitable for use in a topic pattern. +Each time @racket[?] (or @racket[(wild)]) is used in an expression +context, it produces a fresh topic wildcard, suitable for use in a +topic pattern. } @@ -170,9 +179,17 @@ handler's @tech{endpoint}. @section{Actions} +@declare-exporting[marketplace] + @deftogether[( -@deftype[(Action State) (U (PreAction State) (yield State) (at-meta-level State))] -@deftype[(PreAction State) (U (add-endpoint State) delete-endpoint send-message (spawn State) quit)] +@deftype[(Action State) (U (PreAction State) + (yield State) + (at-meta-level State))] +@deftype[(PreAction State) (U (add-endpoint State) + delete-endpoint + send-message + (spawn State) + quit)] )]{ Actions are requests from a process to its containing VM. If wrapped @@ -237,7 +254,9 @@ Deletes an existing endpoint named @racket[pre-eid]. The given @racket[absence-event]. If no specific reason is needed, it is conventional to supply -@racket[#f] as the @racket[delete-endpoint-reason]. +@racket[#f] as the @racket[delete-endpoint-reason]. See also the +convenience @from[marketplace/sugar-values]{@racket[delete-endpoint]} +function from @racket[marketplace/sugar-values]. } @@ -250,8 +269,10 @@ Sends a message to peers.@note{Or, if @racket[at-meta-level], peers of the containing VM.} The given @racket[Orientation] should describe the role the sender is playing when sending this message: usually, it will be @racket['publisher], but when the message is @emph{feedback} for -some publisher, it will be @racket['subscriber]. See also -@racket[send-feedback]. +some publisher, it will be @racket['subscriber]. +@from[marketplace/sugar-values]{See also the @racket[send-message] and +@racket[send-feedback] convenience functions from +@racket[marketplace/sugar-values].} } diff --git a/marketplace/scribblings/management-and-monitoring.scrbl b/marketplace/scribblings/management-and-monitoring.scrbl index 9b72f8c..05c8e73 100644 --- a/marketplace/scribblings/management-and-monitoring.scrbl +++ b/marketplace/scribblings/management-and-monitoring.scrbl @@ -2,6 +2,13 @@ @require[racket/include] @include{prelude.inc} +@require[(for-label marketplace/support/spy + marketplace/support/debug + marketplace/log-untyped + (except-in marketplace/log-typed + matrix-log + matrix-root-logger))] + @title{Management and Monitoring} @section{generic-spy} diff --git a/marketplace/scribblings/prelude.inc b/marketplace/scribblings/prelude.inc index 27547b8..8c50c49 100644 --- a/marketplace/scribblings/prelude.inc +++ b/marketplace/scribblings/prelude.inc @@ -6,9 +6,15 @@ slideshow/pict "vm-pictures.rkt" + "from.rkt" + (for-syntax racket) (for-label typed/racket/base)) +(require (for-label (except-in marketplace/sugar-untyped transition/no-state) + (only-in marketplace/drivers/tcp-bare tcp) + (except-in marketplace/sugar-typed ?))) + ;; TODO: make it display "=" instead of ":" connecting the defined ;; type to the definition. (define-syntax deftype