Docstring for decorated functions

[Brian Carper]

Functions like `link-to` take an optional attribute map as the first
parameter, thanks to being decorated with `optional-attrs`. But if
you look at (doc link-to) it doesn't mention this at all. This is
kind of confusing. The parameter list `doc` lists for `link-to` is
wrong. There's no way to tell exactly what parameters are safe to
pass to `link-to` without knowing that it's decorated with `optional-
attrs`, and then knowing what `optional-attrs` does.

What if `redef` took a docstring argument and appended it to the
docstring of the functions it's decorating? This is a rough idea of
what I mean (in control.clj):

(defmacro redef
"Redefine an existing value, keeping the metadata intact."
[name value new-doc]
`(let [m# (meta #'~name)
v# (def ~name ~value)
doc# (if-let [old-doc# (:doc m#)]
(str old-doc# ~new-doc)
~new-doc)]
(alter-meta! v# merge (assoc m# :doc doc#))
v#))

(defmacro decorate-with
"Wrap multiple functions in a decorator."
[decorator & funcs]
`(do ~@(for [f funcs]
`(redef ~f (~decorator ~f)
(str "\n\n** Decorated with " (:name (meta
#'~decorator)) ":\n"
(with-out-str (doc ~decorator)))))))

Then you have:

user> (doc compojure.html.page-helpers/link-to)
-------------------------
compojure.html.page-helpers/link-to
([url & content])
Wraps some content in a HTML hyperlink with the supplied URL.

** Decorated with optional-attrs:
-------------------------
compojure.html.gen/optional-attrs
([func])
Adds an optional attribute map to the supplied function's arguments.

This still doesn't show you the proper parameter list, but at least it
gives you a hint that something was changed and a place to start
looking.

[James Reeves]

This seems a rather good idea. I'll look into implementing it.

- James