Idiomatic way to document Clojure defn's [closed]

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 5 years ago.

Improve this question

What is the idiomatic way to document function definitions (defn) in Clojure? In particular, should we use "@param", "@returns", etc开发者_JAVA技巧. 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.