Show required parameters within documentation

[mkaschenko]

At the moment clojure.repl/doc shows documentation defined with -- :doc only.
It would be nice if function signatures are shown too like Yesql does https://github.com/krisajenkins/yesql#one-file-one-query.
I think it's handy to know which parameters are required within an sql query.

(clojure.repl/doc users-by-country)

;=> -------------------------
;=> user/users-by-country
;=> ([{:keys [country_code]}]
;=>  [{:keys [country_code]} {:keys [connection]}])
;=>
;=>   Counts the users in a given country.

[csummers]

I think this is a good idea for the simple case of parameters directly defined in the SQL. However, it's worth noting that HugSQL's support for Clojure Expressions and dynamic, run-time parameters make support for this only partially possible since you can essentially create parameters on-the-fly at runtime.

Also related to this, I'm thinking about how to support and use Clojure Spec in the upcoming Clojure 1.9, which includes support for function signature documentation based on the given spec.

Thanks for the request. I'll consider putting the simple case into a future release.

[mkaschenko]

Thank you.

On Oct 9, 2016, at 20:47, Curtis Summers notifications@github.com wrote:

I think this is a good idea for the simple case of parameters directly defined in the SQL. However, it's worth noting that HugSQL's support for Clojure Expressions and dynamic, run-time parameters make support for this only partially possible since you can essentially create parameters on-the-fly at runtime.

Also related to this, I'm thinking about how to support and use Clojure Spec in the upcoming Clojure 1.9, which includes support for function signature documentation based on the given spec.

Thanks for the request. I'll consider putting the simple case into a future release.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub, or mute the thread.

[crinklywrappr]

+1

[liotev]

+1
Currently this issue is the only reason I am using yesql instead of hugsql. Having the key names in the doc string is very helpful.