From c31d352f2bb9498daed8bc4757655c4396b4ba2e Mon Sep 17 00:00:00 2001 From: Guillaume Marceau Date: Fri, 15 Jul 2011 03:27:27 -0400 Subject: [PATCH] Standartize the vocabulary to "the function returns" and "set! mutates" --- collects/2htdp/batch-io.rkt | 2 +- .../private/clauses-spec-and-process.rkt | 2 +- collects/2htdp/private/launch-many-worlds.rkt | 2 +- collects/2htdp/private/world.rkt | 4 +-- collects/2htdp/tests/test-image.rkt | 2 +- collects/2htdp/universe.rkt | 4 +-- collects/htdp/convert.rkt | 2 +- collects/htdp/error-composition.scrbl | 25 ++++++++++++------- collects/htdp/hangman.rkt | 2 +- collects/htdp/htdp-lib.scrbl | 8 +++--- collects/htdp/tests/convert.rkt | 4 +-- collects/lang/private/advanced-funs.rkt | 6 ++--- collects/lang/private/beginner-funs.rkt | 12 ++++----- collects/lang/private/intermediate-funs.rkt | 2 +- collects/lang/private/teachprims.rkt | 4 +-- .../scribblings/htdp-langs/advanced.scrbl | 13 +++++----- collects/scribblings/htdp-langs/prim-ops.rkt | 12 ++++----- collects/tests/htdp-lang/intm-adv.rktl | 2 +- 18 files changed, 58 insertions(+), 50 deletions(-) diff --git a/collects/2htdp/batch-io.rkt b/collects/2htdp/batch-io.rkt index c44a1ff5ca..4684b6218c 100644 --- a/collects/2htdp/batch-io.rkt +++ b/collects/2htdp/batch-io.rkt @@ -41,7 +41,7 @@ write-file ;; String String -> String ;; (write-file filename str) writes str to filename; - ;; produces the file name as a confirmation that the write succeeded + ;; returns the file name as a confirmation that the write succeeded ) ;; ----------------------------------------------------------------------------- diff --git a/collects/2htdp/private/clauses-spec-and-process.rkt b/collects/2htdp/private/clauses-spec-and-process.rkt index 04adcdbbea..df541abd53 100644 --- a/collects/2htdp/private/clauses-spec-and-process.rkt +++ b/collects/2htdp/private/clauses-spec-and-process.rkt @@ -91,7 +91,7 @@ (if r ((third s) r) (fourth s))) Spec)) -;; check whether rec? occurs, produce list of keyword x clause pairs +;; check whether rec? occurs, returns list of keyword x clause pairs (define (clauses-use-kwd stx:list ->rec? tag kwds) (define kwd-in? (->kwds-in kwds)) (map (lambda (stx) diff --git a/collects/2htdp/private/launch-many-worlds.rkt b/collects/2htdp/private/launch-many-worlds.rkt index 7049734e6d..3aabcce6a6 100644 --- a/collects/2htdp/private/launch-many-worlds.rkt +++ b/collects/2htdp/private/launch-many-worlds.rkt @@ -6,7 +6,7 @@ launch-many-worlds ;; (launch-many-worlds e1 ... e2) ;; run expressions e1 through e2 in parallel, - ;; produce all values + ;; return all values ) (define-syntax-rule diff --git a/collects/2htdp/private/world.rkt b/collects/2htdp/private/world.rkt index bbe007b854..7099212e7e 100644 --- a/collects/2htdp/private/world.rkt +++ b/collects/2htdp/private/world.rkt @@ -129,7 +129,7 @@ (height (if (pair? to-draw) (third to-draw) #f))) ;; the visible world - (field [enable-images-button void] ;; used if stop-when call produces #t + (field [enable-images-button void] ;; used if stop-when call returns #t [disable-images-button void] [visible (new pasteboard%)]) @@ -334,7 +334,7 @@ (show (ppdraw))) ;; -> Scene - ;; produce the scene for the this state + ;; return the scene for the this state (define/public (ppdraw) (check-scene-result (name-of draw 'your-draw) (draw (send world get)))) diff --git a/collects/2htdp/tests/test-image.rkt b/collects/2htdp/tests/test-image.rkt index 26bc640223..c237ccfefa 100644 --- a/collects/2htdp/tests/test-image.rkt +++ b/collects/2htdp/tests/test-image.rkt @@ -1380,7 +1380,7 @@ => 128) -;; Rotation by 0 should produce an equivalent object +;; Rotation by 0 should return an equivalent object (test (rotate 0 (make-object image-snip% green-blue-20x10-bitmap)) => (to-img (make-object image-snip% green-blue-20x10-bitmap))) diff --git a/collects/2htdp/universe.rkt b/collects/2htdp/universe.rkt index 7d382c7049..c28e444a8b 100644 --- a/collects/2htdp/universe.rkt +++ b/collects/2htdp/universe.rkt @@ -35,7 +35,7 @@ (provide launch-many-worlds ;; (launch-many-worlds e1 ... e2) - ;; run expressions e1 through e2 in parallel, produce all values in same order + ;; run expressions e1 through e2 in parallel, return all values in same order ) (provide-primitive @@ -123,7 +123,7 @@ ;; ****************************************************************** DEFAULT #'(lambda (u w) (make-bundle u '() '())) ;; this is the wrong default function - ;; instead of K there should be a function that produces a bundle + ;; instead of K there should be a function that returns a bundle (function-with-arity 2) ;; ****************************************************************** ] diff --git a/collects/htdp/convert.rkt b/collects/htdp/convert.rkt index 57fe05b29f..9e994bb831 100644 --- a/collects/htdp/convert.rkt +++ b/collects/htdp/convert.rkt @@ -91,7 +91,7 @@ ;; ------------------------------------------------------------------------ (define OUT-ERROR - "The conversion function must produce a number; result: ~e") + "The conversion function must return a number, but it returned ~e") ;; ============================================================================ ;; MODEL diff --git a/collects/htdp/error-composition.scrbl b/collects/htdp/error-composition.scrbl index 1d3107a898..67b39533f4 100755 --- a/collects/htdp/error-composition.scrbl +++ b/collects/htdp/error-composition.scrbl @@ -2,10 +2,9 @@ @(require scribble/manual (for-label [only-in lang/htdp-advanced set!] - [only-in lang/htdp-intermediate let] - [only-in lang/htdp-beginner define] - [only-in racket/base syntax-local-expand-expression] - )) + [only-in lang/htdp-intermediate let] + [only-in lang/htdp-beginner define] + [only-in racket/base syntax-local-expand-expression])) @(require scribble/decode) @@ -51,7 +50,7 @@ from other teachpacks. nor antagonistic.} @item{If an expression contains multiple errors, report the leftmost - error first. E.g., the error in @racket{(define 1 2 3)} is + error first. E.g., the error in @racket[(define 1 2 3)] is @samp{expected the variable name, but found a number}, not @samp{expected 2 parts after define, but found 3}. Before raising an error about a sub-part of a macro, call @@ -71,7 +70,7 @@ Use only the following vocabulary words to describe code: @list[@para{structure name} @para{type name} @para{field name} @para{binding}]]] @itemize[ - @item{Use binding for the square-braced pair in a @racket{let} + @item{Use binding for the square-braced pair in a @racket[let] and similar binding forms.} @item{Use @word{argument} for actual arguments and @word{variable} for @@ -86,6 +85,8 @@ Use only the following vocabulary words to describe code: @section{Words For Describing Runtime Behavior} +Use the following vocabulary words to describe how code runs: + @itemize[ @item{When specifying a function's behavior, say @samp{the function takes ... and returns ...}} @@ -94,12 +95,18 @@ Use only the following vocabulary words to describe code: expects ... but received ...}} @item{As much as possible, identify expressions and the value they evaluate - to, e.g. @samp{the value of @racket{(f x)} is 5}. If it is necessary to + to, e.g. @samp{the value of @racket[(f x)] is 5}. If it is necessary to mention evaluation order, such as when the context discusses mutable state, say that the expression @samp{evaluates to} a value. Function calls are a special case of expression. Prefer @samp{the function call returns ...} to @samp{the function call evaluates to ...}, except when trying to draw attention to - the evaluation of the arguments.}] + the evaluation of the arguments.} + + @item{@racket[set!] and + @racketidfont{set-}@racket[_structure-name]@racketidfont{-}@racket[_field-name]@racketidfont{!} + @word{mutate} variables and structure instances, respectively. Avoid using + the verb @word{sets} when discussing mutation, and reserve the verbs + @word{changes} and @word{updates} for functional updates.}] @section{Prohibited Words} @@ -157,7 +164,7 @@ not appreciate anyway). [Rationale: Students learn this distinction when they learn about lambda. The first is the lambda implicit in the definition, the second is the variable introduced by the definition that can appear - as the first argument to @racket{set!}, the third is the particular + as the first argument to @racket[set!], the third is the particular sequence of letters. But BSL should avoid this complexity, and ASL’s error messages should maintain consistency with BSL.]} diff --git a/collects/htdp/hangman.rkt b/collects/htdp/hangman.rkt index ed5501c46b..9b58179a08 100644 --- a/collects/htdp/hangman.rkt +++ b/collects/htdp/hangman.rkt @@ -114,7 +114,7 @@ (define message-panel #f) ;; setup-gui : str ->* message% panel% -;; to produce a status message and a panel where winning/losing can be announced +;; to return a status message and a panel where winning/losing can be announced ;; effect: set up a new frame, arrange the GUI, and display (blank) status word (define (setup-gui status) (local (#| -------------------------------------------------------------- diff --git a/collects/htdp/htdp-lib.scrbl b/collects/htdp/htdp-lib.scrbl index 154150320a..90e3eb390c 100755 --- a/collects/htdp/htdp-lib.scrbl +++ b/collects/htdp/htdp-lib.scrbl @@ -154,12 +154,12 @@ they can be syntactically restricted to application positions. @racket[id] is exported as the primitive operator named @racket[id]. An alternative to @racket[define-higher-order-primitive].} -@defform[(first-order->higher-order expr)]{ +@defform[(first-order->higher-order expression)]{ -If @racket[expr] is an identifier for a first-order function (either a -primitive or a function defined within Beginner Student), produces the +If @racket[expression] is the name of a first-order function (either a +primitive or a function defined within Beginner Student), returns the function as a value; otherwise, the form is equivalent to -@racket[expr]. +@racket[expression]. This form is mainly useful for implementing syntactic forms that, like the application of a higher-order primitive, allow first-order bindings diff --git a/collects/htdp/tests/convert.rkt b/collects/htdp/tests/convert.rkt index 313aa9e310..9ff964b336 100644 --- a/collects/htdp/tests/convert.rkt +++ b/collects/htdp/tests/convert.rkt @@ -35,11 +35,11 @@ (convert-file IN f2c OUT) (with-input-from-file OUT check-convert-out) -(check-error (convert-file IN list OUT) "convert: The conversion function must produce a number; result: (212)") +(check-error (convert-file IN list OUT) "convert: The conversion function must return a number; but it returned (212)") (check-error (convert-file IN first OUT) "first: expected argument of type ; given 212") -(check-error (convert-file IN fx OUT) "convert: The conversion function must produce a number; result: xyz") +(check-error (convert-file IN fx OUT) "convert: The conversion function must return a number; but it returned xyz") (check-error (convert-file IN f2c 10) "convert-file: expected as third argument, given: 10") diff --git a/collects/lang/private/advanced-funs.rkt b/collects/lang/private/advanced-funs.rkt index a64e3157c0..42c59cf9c7 100644 --- a/collects/lang/private/advanced-funs.rkt +++ b/collects/lang/private/advanced-funs.rkt @@ -31,7 +31,7 @@ (with-input-from-string (string (-> any) -> any) "Turns the given string into input for read* operations.") (with-output-to-string (string (-> any) -> any) - "Produces a string from all write/display/print operations.") + "Returns a string from all write/display/print operations.") (print (any -> void) @@ -63,7 +63,7 @@ (assoc (any (listof any) -> (listof any) or false) - "Produces the first element on the list whose first is equal? to v; otherwise it produces false.")) + "Returns the first element on the list whose first is equal? to v; otherwise it returns false.")) ("Misc" (gensym (-> symbol?) @@ -75,7 +75,7 @@ (force (delay -> any) "Finds the delayed value; see also delay.") (promise? (any -> boolean) "Determines if a value is delayed.") - (void (-> void) "Produces a void value.") + (void (-> void) "Returns a void value.") (void? (any -> boolean) "Determines if a value is void.")) ("Posns" diff --git a/collects/lang/private/beginner-funs.rkt b/collects/lang/private/beginner-funs.rkt index 27dc2860df..67a0c93351 100644 --- a/collects/lang/private/beginner-funs.rkt +++ b/collects/lang/private/beginner-funs.rkt @@ -290,13 +290,13 @@ "Evaluates the number of items on a list.") (memq (any (listof any) -> (union false list)) "Determines whether some value is on some list" - " if so, it produces the suffix of the list that starts with x" - " if not, it produces false." + " if so, it returns the suffix of the list that starts with x" + " if not, it returns false." " (It compares values with the eq? predicate.)") (memv (any (listof any) -> (union false list)) "Determines whether some value is on the list" - " if so, it produces the suffix of the list that starts with x" - " if not, it produces false." + " if so, it returns the suffix of the list that starts with x" + " if not, it returns false." " (It compares values with the eqv? predicate.)") ((beginner-member? member?) (any (listof any) -> boolean) "Determines whether some value is on the list" @@ -405,7 +405,7 @@ (string (char ... -> string) "Builds a string of the given characters.") (make-string (nat char -> string) - "Produces a string of given length" + "Returns a string of given length" " from a single given character.") (string-ref (string nat -> char) "Extracts the i-the character from a string.") @@ -455,7 +455,7 @@ "Converts a string into a symbol.") (string->number (string -> (union number false)) "Converts a string into a number," - " produce false if impossible.") + " return false if impossible.") (string->list (string -> (listof char)) "Converts a string into a list of characters.") (list->string ((listof char) -> string) diff --git a/collects/lang/private/intermediate-funs.rkt b/collects/lang/private/intermediate-funs.rkt index 4018c35f3d..67e73b3d98 100644 --- a/collects/lang/private/intermediate-funs.rkt +++ b/collects/lang/private/intermediate-funs.rkt @@ -52,7 +52,7 @@ "Finds the (first) element of the list that maximizes the output of the function.") (memf ((X -> any) (listof X) -> (union false (listof X))) - "Determines whether the first argument produces a non-false value for any item in the second argument.") + "Determines whether the function fiven as the first argument returns a non-false value for any item in the second argument.") (apply ((X-1 ... X-N -> Y) X-1 ... X-i (list X-i+1 ... X-N) -> Y) "Applies a function using items from a list as the arguments.") (compose ((Y-1 -> Z) ... (Y-N -> Y-N-1) (X-1 ... X-N -> Y-N) -> (X-1 ... X-N -> Z)) diff --git a/collects/lang/private/teachprims.rkt b/collects/lang/private/teachprims.rkt index c9b191c341..a3145367f1 100644 --- a/collects/lang/private/teachprims.rkt +++ b/collects/lang/private/teachprims.rkt @@ -352,8 +352,8 @@ namespace. (define r (f i)) (unless (char? r) (hocheck 'build-string - "the second argument must be a function that produces a character, ~ - given ~e, which produced ~e for ~e" f r i)) + "the second argument must be a function that returns a character, ~ + given ~e, which returned ~e when given ~e" f r i)) r)))) diff --git a/collects/scribblings/htdp-langs/advanced.scrbl b/collects/scribblings/htdp-langs/advanced.scrbl index 2402c36abc..e820ec6a65 100644 --- a/collects/scribblings/htdp-langs/advanced.scrbl +++ b/collects/scribblings/htdp-langs/advanced.scrbl @@ -91,7 +91,8 @@ @; ---------------------------------------------------------------------- @section[#:tag "advanced-syntax"]{Syntax for Advanced} -In Advanced, @racket[set!] can be used to change variables. @racket[define] and +In Advanced, @racket[set!] can be used to mutate variables, and +@racket[define-struct]'s structures are mutatable. @racket[define] and @racket[lambda] can define functions of zero arguments, and function calls can invoke functions of zero arguments. @@ -155,17 +156,17 @@ the @racket[begin] expression is the value of the first @racket[expression].} @defform[(set! variable expression)]{ -Evaluates @racket[expression], and then changes the definition @racket[variable] +Evaluates @racket[expression], and then mutates the @racket[variable] to have @racket[expression]'s value. The @racket[variable] must be defined by @racket[define], @racket[letrec], @racket[let*], or @racket[let].} @defform[(delay expression)]{ -Produces a ``promise'' to evaluate @racket[expression]. The @racket[expression] +Returns a ``promise'' to evaluate @racket[expression]. The @racket[expression] is not evaluated until the promise is forced with @racket[force]; when the promise is forced, the result is recorded, so that any further -@racket[force] of the promise immediately produces the remembered value.} +@racket[force] of the promise immediately returns the remembered value.} @@ -262,7 +263,7 @@ error.} @defform[(unless test-expression body-expression)]{ Like @racket[when], but the @racket[body-expression] is evaluated when the -@racket[test-expression] produces @racket[false] instead of @racket[true].} +@racket[test-expression] evaluates to @racket[false] instead of @racket[true].} @section[#:tag "advanced-common-syntax"]{Common Syntaxes} @@ -291,7 +292,7 @@ level as they did in the @secref["intermediate-lam"] level. @itemize[ @item{@racketidfont{set-}@racket[_structure-name]@racketidfont{-}@racket[_field-name]@racketidfont{!} : takes an instance of the structure and a value, and - changes the instance's field to the given value.}]} + mutates the instance's field to the given value.}]} define-wish cond else diff --git a/collects/scribblings/htdp-langs/prim-ops.rkt b/collects/scribblings/htdp-langs/prim-ops.rkt index 473e39851b..034e2fcbf7 100644 --- a/collects/scribblings/htdp-langs/prim-ops.rkt +++ b/collects/scribblings/htdp-langs/prim-ops.rkt @@ -312,22 +312,22 @@ (#,check-error-elem expression)]]{ Checks that the @racket[expression] reports an error, - where the error messages matches the string produced by the - @racket[matchexpression], if it is present.} + where the error messages matches the + value of @racket[matchexpression], if it is present.} @defform*[#:id [check-member-of check-member-of-id] [(check-member-of expression expression expression ...)]]{ - Checks that the first @racket[expression] produces the same value - as one of the following @racket[expression]s.} + Checks that the value of the first @racket[expression] as that of + one of the following @racket[expression]s.} @defform*[#:id [check-range check-range-id] [(check-range expression low-expression high-expression)]]{ - Checks that the first @racket[expression] produces a number in - between the numbers produced by @racket[low-expression] and + Checks that the value of the first @racket[expression] is a number in + between the value of the @racket[low-expression] and the @racket[high-expression], inclusive.} @; ---------------------------------------------------------------------- diff --git a/collects/tests/htdp-lang/intm-adv.rktl b/collects/tests/htdp-lang/intm-adv.rktl index ff76b0b5f8..841d5818b7 100644 --- a/collects/tests/htdp-lang/intm-adv.rktl +++ b/collects/tests/htdp-lang/intm-adv.rktl @@ -106,7 +106,7 @@ "foldl : first argument must be a function that expects two arguments, given #") (htdp-err/rt-test (build-string 2 add1) - "build-string : the second argument must be a function that produces a character, given #, which produced 1 for 0") + "build-string : the second argument must be a function that returns a character, given #, which returned 1 when given 0") (htdp-test 0 '+ (+)) (htdp-test 1 '+ (+ 1))