add comments:

-make clear difference between http-error and
fatal-syntax-error
-refer to make-error-response for args of http-error

scheme/httpd/error.scm

@@ -23,19 +23,37 @@
 
 (define http-error? (condition-predicate 'http-error))
 
+;; See make-error-response for what you have to stuff into args for
+;; each status-code. (All http-errors will be caught by the top-level
+;; error-handler of process-toplevel-request, and will be turned into
+;; calls of make-error-response).
 (define (http-error status-code req . args)
   (apply signal 'http-error status-code req args))
 
+
 ;;; Syntax error condition
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;; Scheme 48 has a "syntax error" error condition, but it isn't an error
 ;;; condition! It's a warning condition. I don't understand this. 
 ;;; We define a *fatal* syntax error here for the parsers to use.
 
+
+;; fatal-syntax-error isn't really a different type of error - it's
+;; just an abbreviated notation:
+;; (fatal-syntax-error msg irritants) 
+;; is equivalent to
+;; (http-error (status-code bad-request) #f msg irritants)
+;; -> use fatal-syntax-error where the client request cannot be parsed
+;; because of bad syntax
+
 (define-condition-type 'fatal-syntax-error '(error))
 
 (define fatal-syntax-error? (condition-predicate 'fatal-syntax-error))
 
+;; as with http-errors fatal-syntax-errors will be caught by the
+;; top-level error-handler of process-toplevel-request and turned into
+;; calls of make-error-response
 (define (fatal-syntax-error msg . irritants)
   (apply signal 'fatal-syntax-error msg irritants))
 
+