From 03899c77f1883ac42396a10882756c66666eca89 Mon Sep 17 00:00:00 2001
From: ben <types@ccs.neu.edu>
Date: Mon, 14 Dec 2015 02:32:47 -0500
Subject: [PATCH] ** update inline comments

---
 LICENSE.txt          |  2 +-
 format.rkt           | 21 +++++++++++++--------
 info.rkt             |  2 +-
 math.rkt             | 20 ++++++++++++++------
 private/README.md    |  1 +
 private/common.rkt   |  5 ++---
 regexp.rkt           | 13 ++++++++-----
 test/format-fail.rkt |  2 ++
 test/format-pass.rkt |  2 ++
 test/math-fail.rkt   |  4 ++++
 test/math-pass.rkt   |  2 ++
 test/regexp-fail.rkt |  4 ++++
 test/regexp-pass.rkt |  2 ++
 13 files changed, 56 insertions(+), 24 deletions(-)

diff --git a/LICENSE.txt b/LICENSE.txt
index c65068d..8476131 100644
--- a/LICENSE.txt
+++ b/LICENSE.txt
@@ -1,4 +1,4 @@
-glob
+trivial
 Copyright (c) 2015 Ben Greenman
 
 This package is distributed under the GNU Lesser General Public
diff --git a/format.rkt b/format.rkt
index 49ac936..39dbbf0 100644
--- a/format.rkt
+++ b/format.rkt
@@ -1,5 +1,7 @@
 #lang typed/racket/base
 
+;; Statically-checked format strings
+
 (provide
   format:
   ;; (-> (x:String) Any *N Void)
@@ -17,7 +19,10 @@
 )
 
 (require
-  (for-syntax typed/racket/base syntax/parse racket/sequence))
+  (for-syntax
+    typed/racket/base
+    syntax/parse
+    racket/sequence))
 
 ;; =============================================================================
 
@@ -29,7 +34,7 @@
            [num-expected (length type*)]
            [num-given (for/sum ([a (in-syntax #'(arg* ...))]) 1)])
       (unless (= num-expected num-given)
-        (raise-arity-error
+        (apply raise-arity-error
           (syntax-e #'f)
           num-expected
           (for/list ([a (in-syntax #'(arg* ...))]) (syntax->datum a))))
@@ -45,6 +50,7 @@
    [(f tmp arg* ...)
     (syntax/loc #'f (format tmp arg* ...))]))
 
+;; Short for `(displayln (format: ...))`
 (define-syntax printf:
   (syntax-parser
    [f:id
@@ -55,10 +61,10 @@
 ;; -----------------------------------------------------------------------------
 
 ;; Count the number of format escapes in a string.
-;; Returns a list of optional types (to be spliced into the source code)
-;; Example: If result is '(#f Integer), then
-;; - Expect 2 arguments to format string
-;; - First argument has no constraints, second must be an Integer
+;; Returns a list of optional types (to be spliced into the source code).
+;;   Example: If result is '(#f Integer), then
+;;   - The format string expects 2 arguments
+;;   - First argument has no type constraints, second must be an Integer
 ;; (: count-format-escapes (->* [String] [#:src (U #f Syntax)] (Listof (U #f Syntax))))
 (define-for-syntax (template->type* str #:src [stx #f])
   (define last-index (- (string-length str) 1))
@@ -67,7 +73,7 @@
      [(>= i last-index)
       (reverse acc)]
      [(eq? #\~ (string-ref str i))
-      ;; From fprintf docs
+      ;; From fprintf docs @ http://docs.racket-lang.org/reference/Writing.html
       (case (string-ref str (+ i 1))
        [(#\% #\n #\~ #\space #\tab #\newline)
         ;; Need 0 arguments
@@ -93,4 +99,3 @@
           (string-ref str (+ i 1)))])]
      [else
       (loop (+ i 1) acc)])))
-
diff --git a/info.rkt b/info.rkt
index fcec4b0..0f95608 100644
--- a/info.rkt
+++ b/info.rkt
@@ -4,6 +4,6 @@
 (define deps '("base"))
 (define build-deps '("scribble-lib" "racket-doc" "rackunit-lib"))
 (define pkg-desc "Strongly-typed macros")
-(define version "0.0")
+(define version "0.1")
 (define pkg-authors '(ben))
 (define scribblings '(("scribblings/trivial.scrbl")))
diff --git a/math.rkt b/math.rkt
index 9b53475..662ee39 100644
--- a/math.rkt
+++ b/math.rkt
@@ -1,14 +1,18 @@
 #lang typed/racket/base
 
+;; Constant-folding math operators.
+;; Where possible, they simplify their arguments.
+
 (provide
   +: -: *: /:
-  ;; Fold syntactic constants
+  ;; Same signature as the racket/base operators,
+  ;;  but try to simplify arguments during expansion.
 )
 
 (require (for-syntax
-  racket/base
+  typed/racket/base
   (only-in racket/format ~a)
-  racket/syntax
+  (only-in racket/syntax format-id)
   syntax/id-table
   syntax/parse
   trivial/private/common
@@ -41,10 +45,14 @@
 
 ;; -----------------------------------------------------------------------------
 
+;; Simplify a list of expressions using an associative binary operator.
+;; Return either:
+;; - A numeric value
+;; - A list of syntax objects, to be spliced back in the source code
 (define-for-syntax (reduce/op op e*)
-  (let loop ([prev #f]
-             [acc  '()]
-             [e*   e*])
+  (let loop ([prev #f]   ;; (U #f Number), candidate for reduction
+             [acc  '()]  ;; (Listof Syntax), irreducible arguments
+             [e*   e*])  ;; (Listof Syntax), arguments to process
     (if (null? e*)
       ;; then: finished, return a number (prev) or list of expressions (acc)
       (if (null? acc)
diff --git a/private/README.md b/private/README.md
index 82e5bd0..49a1394 100644
--- a/private/README.md
+++ b/private/README.md
@@ -2,4 +2,5 @@ private
 ===
 
 Files that no law-abiding library user should `require`.
+
 - `common.rkt` Helper functions common to a few macros.
diff --git a/private/common.rkt b/private/common.rkt
index ba242ad..ec75daf 100644
--- a/private/common.rkt
+++ b/private/common.rkt
@@ -1,7 +1,6 @@
 #lang racket/base
 
 ;; Common helper functions
-;; TODO actually detect the `quote` identifier, don't use eq?
 
 (provide
   expand-expr
@@ -10,13 +9,13 @@
 
   quoted-stx-value?
   ;; (-> Any (U #f Syntax))
-  ;; If the argument is a syntax object representing a quoted #%datum `v`,
+  ;; If the argument is a syntax object representing a quoted datum `v`,
   ;;  return `v`.
   ;; Otherwise, return #f.
 )
 
 (require
-  (for-template (only-in racket/base quote)))
+  (for-template (only-in typed/racket/base quote)))
 
 ;; =============================================================================
 
diff --git a/regexp.rkt b/regexp.rkt
index c436496..1d585b7 100644
--- a/regexp.rkt
+++ b/regexp.rkt
@@ -1,7 +1,9 @@
 #lang typed/racket/base
 
+;; Stronger types for regular expression matching.
+;;
 ;; TODO use syntax-class to abstract over local-expands / check num-groups
-;; TODO groups can be #f. Don't just 'error'
+;; TODO groups can be #f when using | ... any other way?
 
 (provide
   regexp:       define-regexp:
@@ -9,7 +11,8 @@
   byte-regexp:  define-byte-regexp:
   byte-pregexp: define-byte-pregexp:
   ;; Expression and definition forms that try checking their argument patterns.
-  ;; If check succeeds, will remember #groups for calls to `regexp-match:`.
+  ;; If check succeeds, will remember the number of pattern groups
+  ;; for calls to `regexp-match:`.
 
   regexp-match:
   ;; (-> Pattern String Any * (U #f (List String *N+1)))
@@ -17,14 +20,13 @@
   ;; If the pattern is determined statically, result will be either #f
   ;;  or a list of N+1 strings, where N is the number of groups specified
   ;;  the pattern.
-  ;;
   ;; Will raise a compile-time exception if the pattern contains unmatched groups.
 )
 
 (require (for-syntax
-  racket/base
+  typed/racket/base
   (only-in racket/format ~a)
-  racket/syntax
+  (only-in racket/syntax format-id)
   syntax/id-table
   syntax/parse
   trivial/private/common
@@ -107,6 +109,7 @@
     (format "Valid regexp pattern (contains unmatched ~a)" reason)
     str))
 
+;; Dispatch for counting groups
 (define-for-syntax (count-groups v-stx)
   (cond
     [(syntax-property v-stx num-groups-key)
diff --git a/test/format-fail.rkt b/test/format-fail.rkt
index fdc6395..049d7e2 100644
--- a/test/format-fail.rkt
+++ b/test/format-fail.rkt
@@ -16,6 +16,8 @@
   (printf: "hex ~o\n" (exact->inexact 0))
 )))
 
+;; -----------------------------------------------------------------------------
+
 (module+ test
   (require
     rackunit)
diff --git a/test/format-pass.rkt b/test/format-pass.rkt
index a7b857e..685df9c 100644
--- a/test/format-pass.rkt
+++ b/test/format-pass.rkt
@@ -1,5 +1,7 @@
 #lang typed/racket/base
 
+;; Successful use of `format:`
+
 (module+ test
 
   (require
diff --git a/test/math-fail.rkt b/test/math-fail.rkt
index 08b50a0..720d9a9 100644
--- a/test/math-fail.rkt
+++ b/test/math-fail.rkt
@@ -1,5 +1,7 @@
 #lang racket/base
 
+;; Math expressions that fail to typecheck
+
 (define (expr->typed-module expr)
   #`(module t typed/racket/base
       (require trivial/math)
@@ -19,6 +21,8 @@
   (ann (/: 1 1 0) One)
 )))
 
+;; -----------------------------------------------------------------------------
+
 (module+ test
   (require
     rackunit)
diff --git a/test/math-pass.rkt b/test/math-pass.rkt
index 82ea069..5afd11b 100644
--- a/test/math-pass.rkt
+++ b/test/math-pass.rkt
@@ -1,5 +1,7 @@
 #lang typed/racket/base
 
+;; Well-typed math
+
 (module+ test
   (require
     trivial/math
diff --git a/test/regexp-fail.rkt b/test/regexp-fail.rkt
index c798136..42cbf0f 100644
--- a/test/regexp-fail.rkt
+++ b/test/regexp-fail.rkt
@@ -1,5 +1,7 @@
 #lang racket/base
 
+;; Ill-typed `regexp:` expressions
+;;
 ;; TODO why can't I catch errors for (ann ... (List String))? WhydoI need #f?
 
 (define (expr->typed-module expr)
@@ -36,6 +38,8 @@
        (U #f (List String String)))
 )))
 
+;; -----------------------------------------------------------------------------
+
 (module+ test
   (require
     rackunit)
diff --git a/test/regexp-pass.rkt b/test/regexp-pass.rkt
index 1783634..3359fe6 100644
--- a/test/regexp-pass.rkt
+++ b/test/regexp-pass.rkt
@@ -1,5 +1,7 @@
 #lang typed/racket/base
 
+;; Well-typed use of regexp:
+
 (module+ test
 
   (require