Documenting clojure data structures

[Jason Bennett]

Over the last month, I've been learning clojure for my new job, and taking Odersky's scala course on coursera. I've been enjoying my time with clojure much more, but the one thing I miss from scala is the ability to document a data structure. It's really nice in Java/Scala to type in an object and get a list of methods/members that are available, instead of having to trace the code and/or guess.

I've seen things in clojure like defrecord, but have not seen good examples of if this is a good way to give some structure to my data. I don't want to turn clojure into an OO language, but there are times when I'm passing around a large map that it would be nice to be able to know what to expect.

jason

[gaz jones]

you could try using contracts to specify what keys are supposed to be
in the map, or just use pre/post conditions built in to clojure?

https://github.com/fogus/trammel

> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clo...@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+u...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en

[Ben Mabey]

On 10/31/12 12:04 PM, gaz jones wrote:
> you could try using contracts to specify what keys are supposed to be
> in the map, or just use pre/post conditions built in to clojure?
>
> https://github.com/fogus/trammel
>

FYI, it looks like trammel's ideas are being moved over to
https://github.com/clojure/core.contracts.

[Paul deGrandis]

If your concern is passing around associative data, contracts and general membership functions are the two most common approaches.

If you're dealing with some unknown thing, you can see what protocols it satisfies and what functions/operations those protocols specify.
Doc strings should be found on the protocols.

The combination of protocols, contracts, and generative testing will get you very far.

Paul
- - - -
FWIW, I'm currently working towards unifying test.generative and core.contract under a single "spec" backend.  The spec can also be used to generate documentation, perform verification via Alloy, and be queried with core.logic.

[Ben Mabey]

This sounds like a fantastic approach. Do you have any of your thoughts
of how the spec would look like publicly available? (or maybe a github
project)

-Ben

[Paul deGrandis]

This sounds like a fantastic approach.  Do you have any of your thoughts
of how the spec would look like publicly available?  (or maybe a github
project)

It's not in the public currently but I'm hoping to have something together for consumption by Conj (Nov 14th).

At this time, the best supported approach is still protocols, membership functions, contracts, generative testing, and comments - as stated earlier in the thread.

Paul

[Zack Maril]

Not sure this is exactly what you are looking for, but clojure.reflect has been helping me a ton lately. I've written a few wrappers around it that I've found quite useful: 

https://gist.github.com/3990888

Hope this helps!

-Zack