Idiomatic way to document defn's

What is the idiomatic way to document defn's? In particular, should we use @param, @returns, etc. to document parameters, return values, etc. It might be good to have some standard way to specify expected parameter types (other that type hints), especially for a dynamically typed language

Re: Idiomatic way to document defn's

Hi Ralph, There's no established idiom beyond the guidelines at http://dev.clojure.org/display/design/Library+Coding+Standards I am not aware of any tool that parses Clojure docstrings for Javadoc-style @param and @return, although I would like to see that happen. For now, Clojure docstrings

Re: Idiomatic way to document defn's

I've adopted: (defn create-session! Create shared sessions and their associated channel. Arguments: some-req-arg - a vector, something descriptive. [session-id] - a String, the session's identifier. [auto-generated UUID] Returns: m - a MapEntry, the stored session Notes:

Re: Idiomatic way to document defn's

Paul deGrandis paul.degran...@gmail.com writes: (defn create-session! Create shared sessions and their associated channel. Arguments: I've found the two-space indentation to be a brittle convention that's not going to port well to other presentations of the text, or adapt well to a change