<< Back to previous view

[CCONTRACTS-6] Add/improve docs of contract, clojure.core.contracts, etc. Created: 30/Apr/14  Updated: 30/Apr/14

Status: Open
Project: core.contracts
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major
Reporter: Jakub Holy Assignee: Fogus
Resolution: Unresolved Votes: 0
Labels: documentation


 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.

Thank you!






[CCONTRACTS-5] Fix links in and display of documentation Created: 30/Apr/14  Updated: 30/Apr/14

Status: Open
Project: core.contracts
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major
Reporter: Jakub Holy Assignee: Fogus
Resolution: Unresolved Votes: 0
Labels: documentation


 Description   

There is a number of problems with the way the documentation is made available and interlinked:

  • Currently most people likely arrive to https://github.com/clojure/core.contracts and read the README - but it does not point to the docs in ./docs/ => add link to it there
  • It is not clear how the docs are expected to be browsed; I suppose that the .org
    files should be exported to ./docs/wiki/*.markdown yet not all of them are. I also
    suppose that the exported markdown files should be available under https://github.com/clojure/core.contracts/wiki, i.e. pushed to git@github.com:clojure/core.contracts.wiki.git
  • Some of the problems:
  • the link "return to documentation" on e.g. "with-constraints" should point to /clojure/core.contracts/wiki, not /clojure/core.contracts/docs.html
  • if wiki is really exported, the main page should mention it is immutable
  • links on the home page had one more 'wiki' in them (fixed manually in the wiki - will be overriden by the next export)
  • some links are broken, f.ex. [defconstrainedfn](/clojure/core.contracts/wiki/defconstrainedfn) on f.ex. contract; [with-constraints](/clojure/core.contracts/with-constraints/) (missing /wiki/), [defcontract](/clojure/core.contracts/wiki/defcontract/)

It would certainly help the project if the documentation was easier to access and browse

Thank you






Generated at Thu Nov 27 11:26:34 CST 2014 using JIRA 4.4#649-r158309.