CODEWITHSUNDEEP
clojuremetadatadocstring
Dave Yarwood
Dave Yarwood

Reputation: 3010

Documenting functions defined using point-free style

When creating a library in Clojure, it's good practice to include docstrings and other metadata on each function, e.g.:

(defn ^Boolean foo
  "Returns whether x is bar."
  {:added "1.5"}
  [x]
  (bar? x))

Sometimes (when working with higher-order functions) it ends up being easier to define a function using def (something-that-returns-a-fn), like this:

(defn wrapper [f]
  "Some HOF, let's say it just prints 'WHARRGARBL' and then returns the fn."
  (println "WHARRGARBL")
  f)

(def foo
  "Prints 'WHARRGARBL' and then returns whether x is bar."
  (wrapper (fn [x] (bar? x))))

If I'm not mistaken, defining functions in this way nullifies the advantages of using defn -- namely, the docstring being printed in a nice way than includes what arities the function supports, and the ability to concisely include an attribute map inside the function definition. Am I right, or is there some other concise way to document functions created via HOFs? I could just do this:

(defn foo
  "Prints 'WHARRGARBL' and then returns whether x is bar."
  {:added "1.5"}
  [x]
  ((wrapper (fn [y] (bar? y))) x))

but that seems a little redundant and unnecessarily complicated, as I'm defining a function of x to be a function of y, applied to x. Is there a better way?

Upvotes: 2

Views: 239

Answers (1)

A. Webb
A. Webb

Reputation: 26446

You can add whatever metadata you wish with the def.

(def ^{:doc "Does something."
       :added "1.5"
       :arglists '([x]) }
  foo
  (wrapper (fn [x] (bar? x))))

Upvotes: 6

Related Questions