From 4df27aabdbf0304ec877217e7f797842a60de181 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Georges=20Dup=C3=A9ron?= <georges.duperon@gmail.com>
Date: Mon, 5 Sep 2016 00:58:41 +0200
Subject: [PATCH] Documentation.

---
 README.md                            | 12 ++++++++++-
 scribblings/typed-struct-props.scrbl | 31 +++++++++++++++++++++++-----
 2 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index f25c096..2df02a9 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,13 @@
 typed-struct-props
 =========================
-README text here.
+
+This library allows a safer use of some struct type properties with
+Typed/Racket.
+
+* Functions and values supplied to `#:property prop:some-prop value-here` are
+  typechecked. Their type is computed by this library, and depends on the
+  property.
+
+* The API should hopefully remain stable, even if struct type properties
+  become supported (this library will then become a wrapper) or forbidden in
+  Typed/Racket (this library will then use typed/racket/unsafe tricks).
\ No newline at end of file
diff --git a/scribblings/typed-struct-props.scrbl b/scribblings/typed-struct-props.scrbl
index c4d2988..49443d4 100644
--- a/scribblings/typed-struct-props.scrbl
+++ b/scribblings/typed-struct-props.scrbl
@@ -7,24 +7,40 @@
 
 @defmodule[typed-struct-props]
 
-@defform[#:literals (: prop:custom-write )
+@defform[#:literals (: prop:custom-write prop:equal+hash)
          (struct/props maybe-type-vars name ([field : type] ...) options ...)
          #:grammar
          [(maybe-type-vars (code:line)
                            (v ...))
           (options #:transparent
                    (code:line #:property prop:custom-write custom-write)
-                   (code:line #:equal+hash equal+hash))]
+                   (code:line #:property prop:equal+hash equal+hash))]
          #:contracts ([custom-write
-                       (∀ (v ...)
+                       (→ name                    (code:comment "non-polymorphic case")
+                          Output-Port
+                          (U #t #f 0 1)
+                          Any)]
+                      [custom-write
+                       (∀ (v ...)                 (code:comment "polymorphic case")
                           (→ (name v ...)
                              Output-Port
                              (U #t #f 0 1)
                              Any))]
                       [equal+hash
-                       (List (∀ (v ... |v'| ...)
+                       (List (→ name                (code:comment "non-polymorphic case")
+                                name
+                                (→ Any Any Boolean)
+                                Any)
+                             (→ v
+                                (→ Any Integer)
+                                Integer)
+                             (→ v
+                                (→ Any Integer)
+                                Integer))]
+                      [equal+hash
+                       (List (∀ (v ... v2 ...)      (code:comment "polymorphic case")
                                 (→ (name v ...)
-                                   (name |v'| ...)
+                                   (name v2 ...)
                                    (→ Any Any Boolean)
                                    Any))
                              (∀ (v ...)
@@ -38,6 +54,11 @@
  This form defines a @racketmodname[typed/racket] struct type, and accepts a
  small subset of @racketmodname[racket]'s struct type properties.
 
+ For @racket[prop:custom-write] and @racket[prop:equal+hash], the function
+ types are polymorphic only if the struct is polymorphic (i.e. 
+ @racket[maybe-type-vars] is present) and has at least one type variable (i.e. 
+ @racket[maybe-type-vars] is not just @racket[()]).
+
  It implements these struct type properties in a type-safe manner: the current
  implementation in @racketmodname[typed/racket] does not properly type-check
  functions and values used as struct type properties. This library declares the