I've been toying around with the idea of type signatures that exist
specifically for documentation purposes, loosely inspired by the stack
effect declarations in Factor.
For example, in your case we might start with something like:
(defn count-items
{:doc/type '([{Keyword String} -> Integer])}
[m])
And then change it to:
(defn count-items
{:doc/type '([[& [Keyword String]] -> Integer])}
[m])
This might produce docs like:
(count-items {Keyword String}) → Integer
(count-items [& [Keyword String]]) → Integer
Or for more standard functions:
(assoc {k v} k v) → {k v}
(get {k v} k) → v
As you can probably tell, these type definitions wouldn't be sufficient for
core.typed or even Prismatic's schema. Their purpose would be purely to
give end users an approximate understanding of the function at a glance.
I've yet to completely sell myself on this idea, however.
- James
On 17 May 2014 15:22, Mike Fikes <mikefi...@me.com> wrote:
> I've never used a dynamically-typed language and an issue I've encountered
> with Clojure is a difficulty with readily "seeing" the data structures
> being consumed or returned by functions I'm writing, especially when I come
> back to them several days later and if those structures get to be somewhat
> nested or otherwise complex.
>
> As a small concrete example, lets say that I currently have a function
> that accepts data that looks like {:a "A" :b "B"} and, at some point I
> change the internals of the function to instead operate on data that looks
> like [[:a "A"] [:b "B"]].
>
> I could see the docstring communicating that the initial implementation of
> the function accepts a map, and then perhaps it boils down to finding
> suitable language to describe the structure in the revised implementation
> ("sequence of pairs", "relation", or some other language suitable to the
> abstraction).
>
> I suppose this is no different than the "documentation" aspect that
> generics provided in Java when we went from raw types like List to
> List<String>, but, of course, generics can get unwieldy rather quickly with
> things like List<Map<String,Set<Integer>>>.
>
> Does there exist idiomatic language that developers employ in their
> docstrings to quickly convey this kind of info? I see that the docstrings
> for clojure.core are fairly readable, but they tend to operate on very
> simple data structures.
>
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clojure@googlegroups.com
> Note that posts from new members are moderated - please be patient with
> your first post.
> To unsubscribe from this group, send email to
> clojure+unsubscr...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
> ---
> You received this message because you are subscribed to the Google Groups
> "Clojure" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to clojure+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
