Ah, sorry, didn't see your reference at the bottom :)
Schema does augment the docs to some degree:
paddleguru.models.transfer/payout!
([regatta balance our-fee their-fee])
Inputs: [regatta :- regatta/Regatta balance :- graph/Balance our-fee
:- s/Num their-fee :- s/Num]
Returns: {:success s/Bool, :message s/Str}
Performs a payout for the supplied regatta. If either of the
supplied balances can't be satisfied by current available funds,
this method returns success false and a message explaining what
happened. Else, it'll create all transfers and return success and a
nice note.
James Reeves <mailto:ja...@booleanknot.com>
May 17, 2014 11:42 AM
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
--
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
<mailto:clojure+unsubscr...@googlegroups.com>.
For more options, visit https://groups.google.com/d/optout.
Mike Fikes <mailto:mikefi...@me.com>
May 17, 2014 8:22 AM
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
<mailto:clojure+unsubscr...@googlegroups.com>.
For more options, visit https://groups.google.com/d/optout.
--
Sam Ritchie (@sritchie)
Paddleguru Co-Founder
703.863.8561
www.paddleguru.com <http://www.paddleguru.com/>
Twitter <http://twitter.com/paddleguru>// Facebook
<http://facebook.com/paddleguru>
--
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.
