From d16d5f14f3f568e42783e0ecd0781556b5ca2ce1 Mon Sep 17 00:00:00 2001
From: Asumu Takikawa <asumu@ccs.neu.edu>
Date: Tue, 7 May 2013 11:46:40 -0400
Subject: [PATCH] Add examples for syntax/stx

---
 collects/syntax/scribblings/stx.scrbl | 63 ++++++++++++++++++++++++---
 1 file changed, 56 insertions(+), 7 deletions(-)

diff --git a/collects/syntax/scribblings/stx.scrbl b/collects/syntax/scribblings/stx.scrbl
index ea8e066a37..1c5dba97e5 100644
--- a/collects/syntax/scribblings/stx.scrbl
+++ b/collects/syntax/scribblings/stx.scrbl
@@ -1,6 +1,10 @@
 #lang scribble/doc
 @(require "common.rkt" (for-label syntax/stx))
 
+@(require scribble/eval)
+@(define stx-eval (make-base-eval))
+@(stx-eval '(require syntax/stx))
+
 @title[#:tag "stx"]{Deconstructing Syntax Objects}
 
 @defmodule[syntax/stx]
@@ -10,38 +14,80 @@
 Returns @racket[#t] if @racket[v] is either the empty list or a
 @tech[#:doc refman]{syntax object} representing the empty list (i.e.,
 @racket[syntax-e] on the @tech[#:doc refman]{syntax object} returns
-the empty list).}
+the empty list).
+
+@examples[#:eval stx-eval
+  (stx-null? null)
+  (stx-null? #'())
+  (stx-null? #'(a))
+]}
 
 @defproc[(stx-pair? [v any/c]) boolean?]{
 
 Returns @racket[#t] if @racket[v] is either a pair or a syntax object
-representing a pair (see @techlink[#:doc refman]{syntax pair}).}
+representing a pair (see @techlink[#:doc refman]{syntax pair}).
+
+@examples[#:eval stx-eval
+  (stx-pair? (cons #'a #'b))
+  (stx-pair? #'(a . b))
+  (stx-pair? #'())
+  (stx-pair? #'a)
+]}
 
 @defproc[(stx-list? [v any/c]) boolean?]{ 
 
 Returns @racket[#t] if @racket[v] is a list, or if it is a sequence of
 pairs leading to a syntax object such that @racket[syntax->list] would
-produce a list.}
+produce a list.
+
+@examples[#:eval stx-eval
+  (stx-list? #'(a b c d))
+  (stx-list? #'((a b) (c d)))
+  (stx-list? #'(a b (c d)))
+  (stx-list? (list #'a #'b))
+  (stx-list? #'a)
+]}
 
 @defproc[(stx->list [stx-list stx-list?]) (or/c list? #f)]{
 
 Produces a list by flatting out a trailing syntax object using
-@racket[syntax->list].}
+@racket[syntax->list].
+
+@examples[#:eval stx-eval
+  (stx->list #'(a b c d))
+  (stx->list #'((a b) (c d)))
+  (stx->list #'(a b (c d)))
+  (stx->list (list #'a #'b))
+  (stx->list #'a)
+]}
 
 @defproc[(stx-car [v stx-pair?]) any]{
 
-Takes the car of a @techlink[#:doc refman]{syntax pair}.}
+Takes the car of a @techlink[#:doc refman]{syntax pair}.
+
+@examples[#:eval stx-eval
+  (stx-car #'(a b))
+  (stx-car (list #'a #'b))
+]}
 
 @defproc[(stx-cdr [v stx-pair?]) any]{
 
-Takes the cdr of a @techlink[#:doc refman]{syntax pair}.}
+Takes the cdr of a @techlink[#:doc refman]{syntax pair}.
+
+@examples[#:eval stx-eval
+  (stx-cdr #'(a b))
+  (stx-cdr (list #'a #'b))
+]}
 
 @defproc[(stx-map [proc procedure?]
                   [stxl stx-list?] ...)
          list?]{
 
 Equivalent to @racket[(map proc (stx->list stxl) ...)].
-}
+
+@examples[#:eval stx-eval
+  (stx-map (λ (id) (free-identifier=? id #'a)) #'(a b c d))
+]}
 
 @defproc[(module-or-top-identifier=? [a-id identifier?]
 				     [b-id identifier?])
@@ -59,3 +105,6 @@ example, the @racket[include] macro uses this procedure to recognize
 well outside of @racket[module], since the top-level
 @racket[build-path] is a distinct variable from the @racketmodname[racket/base] export
 (though it's bound to the same procedure, initially).}
+
+@close-eval[stx-eval]
+