Add/improve docs of contract, clojure.core.contracts, etc.
Description
Even though contract is a key thing in the library, it lacks a docstring. The docstring of the ns could also have a few words pointing to the main functions and how to use them.
contract
For contract, st. like would be nice (excuse my poor understanding of the lib):
Define a named and documented contract.
constraints => signature-constraint*
signature-constraint => argument-vector constraint-vector
constraint-vector => functions and expressions [=> functions and expressions]
The functions are applied to the arguments, an expressions is executed as-is.
Constraint following `=>` are post-conditions and may use `%` to refer to the return value.
Ex.:
(contract doubler
"ensures doubling (sometimes)"
[x] [number? => integer?]
[x y] [(every? number? [x y])
=>
integer? (= (* 2 (+ x y)) %)])))
See also: with-constraints, defconstrainedfn, and clojure.core.contracts.constraints
ns
The ns docstring could be improved f.ex. like this
The public contracts programming functions and macros for clojure.core.contracts.
Primary usage: defconstrainedfn or contract and with-constraints.
Use provide for functions you don't control.
Other
There are other undocumented or too lightly documented fns/macros that would benefit from improvements, f.ex.
what does _ do?
provide would benefit from a (even brief) example
require-with-constraints - what is it, when to use?
in - an example would be nice
whitelist - the argument should be 'thing' not 'things' to be consistent with the docstring and the fact that it is a single map/set
an example of using implies, <=>, etc. would be nice - currently I don't really know when/why to use it (not mentioning how) [perhaps in the ns docstring, all this functions docstring having "... see the ns docstring")
why is defconstrainedfn in constraints.clj and not contracts.clj as the other main fns? Why does provide use "kontracts" instead of "c" as with-constraints does? (The mismatch of "constraint" and "contract" - fn is with-constraints but takes contracts - is in itself confusing but that is another story.)
defconstrainedrecord has no doc
I would be really happy if at least some of these improvements were applied. I believe it would help to spread contract programming more.
Even though
contractis a key thing in the library, it lacks a docstring.The docstring of the ns could also have a few words pointing to the main functions
and how to use them.
contract
For contract, st. like would be nice (excuse my poor understanding of the lib):
Define a named and documented contract. constraints => signature-constraint* signature-constraint => argument-vector constraint-vector constraint-vector => functions and expressions [=> functions and expressions] The functions are applied to the arguments, an expressions is executed as-is. Constraint following `=>` are post-conditions and may use `%` to refer to the return value. Ex.: (contract doubler "ensures doubling (sometimes)" [x] [number? => integer?] [x y] [(every? number? [x y]) => integer? (= (* 2 (+ x y)) %)]))) See also: with-constraints, defconstrainedfn, and clojure.core.contracts.constraintsns
The ns docstring could be improved f.ex. like this
The public contracts programming functions and macros for clojure.core.contracts. Primary usage: defconstrainedfn or contract and with-constraints. Use provide for functions you don't control.Other
There are other undocumented or too lightly documented fns/macros that would benefit
from improvements, f.ex.
what does _ do?
provide would benefit from a (even brief) example
require-with-constraints - what is it, when to use?
in - an example would be nice
whitelist - the argument should be 'thing' not 'things' to be consistent with the docstring and the fact that it is a single map/set
an example of using implies, <=>, etc. would be nice - currently I don't really know when/why to use it (not mentioning how) [perhaps in the ns docstring, all this functions docstring having "... see the ns docstring")
why is defconstrainedfn in constraints.clj and not contracts.clj as the other main fns?
Why does provide use "kontracts" instead of "c" as with-constraints does? (The mismatch of "constraint" and "contract" - fn is with-constraints but takes contracts - is in itself confusing but that is another story.)
defconstrainedrecord has no doc
I would be really happy if at least some of these improvements were applied. I believe it would help to spread contract programming more.
Thank you!