Specs not shown by :Doc

ghost commented 5 years ago

I have the following Clojure buffer:

(ns vim-fireplace.specs
  (:require [clojure.spec.alpha :as s]
            [clojure.spec.test.alpha :as stest]))

(defn say-hello 
  "Returns a greeting to s."
  [s]
  (str "Hello " s))

(s/fdef say-hello  
  :args (s/cat :s string?))

(stest/instrument `say-hello)

When I do :Doc say-hello it just prints the docstring without the spec:

vim-fireplace.specs/say-hello
[s]
  Returns a greeting to s.

When I do :Eval (clojure.repl/doc say-hello), it prints the full documentation:

-------------------------
vim-fireplace.specs/say-hello
([s])
  Returns a greeting to s.
Spec
  args: (cat :s string?)
  ret: any?

Is there a way to also get the spec when doing :Doc say-hello?

Thanks!

tpope commented 5 years ago

@christoph-frick thoughts on this?

christoph-frick commented 5 years ago

@tpope

If we want to replicate clojure.repl/doc we have to do what they are doing. doc handles two cases for spec: a) show the fdef specs on functions and b) show spec/describe for doc on a keyword (this is handled in #335 in a different way)

I see two routes to go from here:

if we want to provide spec fallbacks for the no-cider/old-cider case in #335, we have work like orchard does and get basically functions like form, describe, explain, ... working. This gives us some responsibility about finding the correct spec-version ("0", alpha 1, alpha 2) and what (mix) the user might actually use. Advantage: provide spec features without cider, option to provide tooling other than cider -- Disadvantage: replicate functionality, that is already there in doc, which brings us to:
instead of replicating the behaviour of clojure.repl/doc, why not just use it? We could do something like assoc-ing :doc-str with (with-out-str (clojure.repl/doc arg)) in fireplace#info and just use that in Doc for the non-java branch (and remove the spec branch in #335). Adv: doc looks like users know it from the REPL, no need to replicate everything from clojure.repl/doc.

tpope commented 5 years ago

Several questions, but I'm gonna start with a dumb one: Why do we need to do a bunch of hand-wringing over the version when clojure.repl itself doesn't seem to?

I don't think jamming extra fields into fireplace#info() makes sense, the whole point of that function is to match what CIDER does. But calling out to clojure.repl/doc directly might be tenable if it can be made to work for ClojureScript too.

Anyone know how Emacs solves this?

christoph-frick commented 5 years ago

+1 for just calling doc - since we are behind already and afaik provide no advantage over it currently. Only problem (since i tried this already) is, that if you have a pretty-printer (e.g. whidbey) in the REPL, the doc will contain e.g. the args pretty printed which gave me lots of color-escape-sequences in the output. So with-out-str alone might not be enough.

tpope / vim-fireplace

Specs not shown by :Doc #325