because you want to be able to document the different implementations differently. The semantics would be: If the function body starts with a string literal, the latter serves as the documentation. If the body consists of any other code following the string literal, it will be ignored for run-time processing; if it's the only thing in the body, it also serves as the return value.
> because you want to be able to document the different implementations differently.
I disagree with this. Since the normal functions cannot dispatch on type⁺, only arity, the different implementations are typically very related and should share same documentation. Your proposal would lead to massive duplication, and reduce the likelihood of people actually documenting the functions.
⁺ There are two separate mechanisms for providing richer function dispatch, both allow more granular documentation.
That could be done as:
(defn function "doc" [a b & rest] "body")
However, matching by arity at the front really helps make simple functions clean. I really like the multiple body approach, as in my code there's typically one "standard" case, and the rest are special cases that just call the standard one with new params. Having to deal with a rest arg with potentially multiple possible lengths just doesn't look as clear in practice.
It's all tradeoffs. I can see why you'd like the arglist first -- I have some Haskell background, and I do miss it's types in Clojure, just for the documentation they provide.
