Welcome! Please see the About page for a little more info on how this works.

0 votes
in core.contracts by
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.

h3. 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.


(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

h3. 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.

h3. 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!

1 Answer

0 votes
Reference: https://clojure.atlassian.net/browse/CCONTRACTS-6 (reported by alex+import)