What is the idiomatic way to document function definitions (defn) in Clojure? In particular, should we use "@param", "@returns", etc. to document parameters, return values, etc.?
Is there some standard way to specify expected parameter types (other that type hints) in this dynamically typed language?
There does not seem to be a very strong tendency to use @param tags though I think they may be more common. the @returns tag it perhaps less applicable because it would make a lot of sense to put the entire description of what the function does under the @returns tag.
typically the code in clojure.core sticks to describing what the function does and a lot of them start with the word "return".
(defn rand-nth
"Return a random element of the (sequential) collection. Will have
the same performance characteristics as nth for the given
collection."
There is a tendency in idomatic clojure code to try to use the build in sequence abstractions for most functions so rand-nth's doc string could look like:
(defn rand-nth
"@Params: any seq
@Returns a random element of the (sequential) collection. Will have
the same performance characteristics as nth for the given
collection."
which does not really say a lot more than the origional.