Display Clojure.spec in the doc buffer

[Malabarba]

According to http://clojure.org/about/spec

Functions specs defined via fdef will appear when you call doc on the fn name. You can call describe on specs to get descriptions as forms

We should probably ensure that cider doc buffers display the same information.

[bbatsov]

Yep, we should probably do this, although 1.9 is not going to be released for a while, so this is definitely not something particularly important right now.

[Malabarba]

Here's an example of what we'd like to display: http://clojure.github.io/java.jdbc/#clojure.java.jdbc/create-table-ddl

[ckoparkar]

I'd like to take this up. I'll submit a PR soon.

[bbatsov]

Great!

[expez]

You still interested in taking this on, @cskksc?

[ckoparkar]

Yep. But I have been traveling for the last couple of weeks. I'll finish this by Tuesday next week :-) Is that ok ?

[bbatsov]

Absolutely. It's not like Clojure 1.9 is even released yet... :-)

[bbatsov]

@cskksc Any updates here?

[ckoparkar]

I'm done with the nREPL changes. The elisp interface should be done soon. Got caught in some university work. Sorry, I forgot to post an update here.

[lvh]

I don't know if it's relevant, but clojure.repl/doc exposes this for you.

[ckoparkar]

@ivh Yep. Even clojure.spec has fn's for this. The nREPL would return (clojure.spec/describe (clojure.spec/get-spec namespace-qualified-var)) and we just have pretty-print this into the doc buffers.

[ckoparkar]

For the ranged-rand example from the guide;

(require '[clojure.spec :as s])

(defn ranged-rand
  "Returns random int in range start <= rand < end."
  [start end]
  (+ start (long (rand (- end start)))))

(s/fdef ranged-rand
        :args (s/and (s/cat :start int? :end int?)
                     #(< (:start %) (:end %)))
        :ret int?
        :fn (s/and #(>= (:ret %) (-> % :args :start))
                   #(< (:ret %) (-> % :args :end))))

this is how our doc buffers would look.

Does it look ok ? I just have to write tests and tidy up some code before submitting a PR.

[ckoparkar]

I mean it looks exactly same as the clojure.repl/doc fn displays it. Do we want to change/add anything ? I was thinking of adding something like "Spec is defined here: hyperlink". I'm not sure if the API provides metadata for this, but I'm gonna check that now. Also, it would only make sense to have something like this for spec's defined in the user controlled namespaces.

[expez]

I think it makes more sense to add the location of the function at the bottom instead of between the docstring and the spec. This is because I view the spec to be part of the documentation.

This is obviously a minor thing, so don't spend any time on it if it's hard to change.

[ckoparkar]

@expez Done :-)

[expez]

👍

[lvh]

Looks awesome to me :)

[Malabarba]

👍

[bbatsov]

Looks good indeed.