Merge pull request bbatsov#103 from llasram/docstring-after-fn-name

Docstring placement.

Author: bbatsov

README.md

@@ -165,6 +165,27 @@ when there are no arguments on the same line as the function name.
   [x] (bar x))
  ```
 
+* <a name="docstring-after-fn-name">
+ When adding a docstring – especially to a function using the above form – take
+ care to correctly place the docstring after the function name, not after the
+ argument vector. The latter is not invalid syntax and won’t cause an error,
+ but includes the string as a form in the function body without attaching it to
+ the var as documentation.
+<sup>[[link](#docstring-after-fn-name)]</sup>
+
+ ```Clojure
+ ;; good
+ (defn foo
+  "docstring"
+  [x]
+  (bar x))
+
+ ;; bad
+ (defn foo [x]
+  "docstring"
+  (bar x))
+ ```
+
 * <a name="oneline-short-fn"></a>
  Optionally omit the new line between the argument vector and a short
  function body.