Documenting specs inline

doc.clj

(defmacro doc
 "Returns a spec which acts in all points like the provided spec,
  expect for describe/form where the docstring appears."
 [docstring spec]
  `(doc-impl ~docstring '~spec (delay (spec/spec ~spec))))

(defn doc-impl [docstring form delayed-spec]
  (reify spec/Spec
    (conform* [_ x] (spec/conform* @delayed-spec x))
    (unform* [_ y] (spec/unform* @delayed-spec y))
    (explain* [_ path via in x] (spec/explain* @delayed-spec path via in x))
    (gen* [_ overrides path rmap] (spec/gen* @delayed-spec overrides path rmap))
    (with-gen* [_ gfn] (spec/with-gen* @delayed-spec gfn))
    (describe* [_]
      `(doc ~docstring ~(if (keyword? form) form (spec/describe* @delayed-spec))))))

Expect or except ?

Christophe, can you give an example of usage with result ?