Question: Does anyone know of work to generate human-readable documentation from specs?

Asked By
bbrinck
Asked At
2017-08-23 20:09:42

Found 15 possible answers.

User Answered At Possible Answer
adamfrey 2017-08-23 20:28:26 it is possible to set the generator of a spec after it's been defined?
alexmiller 2017-08-23 20:43:07 @adamfrey not without re-registering it https://github.com/jebberjeb/specviz there are also one (or maybe more) tools for creating diagrams representing specs @bbrinck autodoc is used to create the clojure docs and it has rudimentary support for including specs
bbrinck 2017-08-23 20:45:30 @alexmiller Thanks!
jebberjeb 2017-08-23 20:46:34 @bbrinck PRs welcome there :slightly_smiling_face:
cddr 2017-08-24 07:35:04 It occurred to me today that for my use-case, I think I can work around it with a macro that expands to a (defmethod, defn) pair and then write fspecs against the defn.
alexmiller 2017-08-24 14:07:01 yes, that should work
jpmonettas 2017-08-24 15:21:53 hi everybody, what's the way to spec something is a promise of some kind
alexmiller 2017-08-24 15:35:50 not really any good way right now I would focus on spec’ing the place where you deliver it and receive it
joshjones 2017-08-24 15:40:32 you could do you could (delay (promise)) elsewhere if you wanted to avoid creating a promise each time you ran the predicate
(s/def ::promise #(= (class %) (class (promise))))
?
alexmiller 2017-08-24 15:47:41 I’m not sure there’s much value in checking just that something is a promise. I presume what is of interest is that it’s a promise that returns something that matches a spec or where you are delivering the value so I think you instead want to validate the spec at the point where you are already retrieving the value however, checking for that would require you to block waiting for the promise to be delivered
jpmonettas 2017-08-24 16:09:08 thanks @joshjones @alexmiller I'm more interested in the doc aspect since it's a :ret I'm not worried about instrument blocking on deref yeah I'm trying to spec a function return that returns a promise with an int?
seancorfield 2017-08-24 16:35:27 Several times I've wanted to be able to spec "this should be an atom containing an X" so I feel the lack @jpmonettas -- but as @alexmiller says, a lot of the times where you would want this, spec would need to deref the container to check the value inside and that's not the correct semantics (it would block). (since you don't mind the checker blocking on a deref to check the value anyway) It would make me want to have the function return int, and instead call it in a future (which has the advantage that the caller controls both the wrapping and the dereference).
mpenet 2017-08-24 16:43:32 You can put a validator on the atom with a valid? check i guess Chan args have a concept of "direction" Golang is interesting for chan args, you can say "this arg is a chan of int that can only be take!en in that scope" etc Wont help with gen tho
alexmiller 2017-08-24 17:12:35 No, that's different. Atom deref is not blocking We might add atom-of eventually
seancorfield 2017-08-24 17:17:48 I meant more in the general "derefable" situation -- but you're right that each type of derefable is different.

Related Questions