diff --git a/NEWS b/NEWS index 3e23f6686..9ec40c6c6 100644 --- a/NEWS +++ b/NEWS @@ -18,6 +18,7 @@ Changes from 0.13.0 * new `comment` macro * support EDN `#_` syntax to discard the next term * `return` has been implemented as a special form + * new `doc` macro and `#doc` tag macro [ Bug Fixes ] * Numeric literals are no longer parsed as symbols when followed by a dot diff --git a/docs/language/api.rst b/docs/language/api.rst index b1a3e1d0a..aa78346db 100644 --- a/docs/language/api.rst +++ b/docs/language/api.rst @@ -480,6 +480,41 @@ Some example usage: ``do`` can accept any number of arguments, from 1 to n. +doc / #doc +---------- + +Documentation macro and tag macro. +Gets help for macros or tag macros, respectively. + +.. code-block:: clj + + => (doc doc) + Help on function (doc) in module hy.core.macros: + + (doc)(symbol) + macro documentation + + Gets help for a macro function available in this module. + Use ``require`` to make other macros available. + + Use ``#doc foo`` instead for help with tag macro ``#foo``. + Use ``(help foo)`` instead for help with runtime objects. + + => (doc comment) + Help on function (comment) in module hy.core.macros: + + (comment)(*body) + Ignores body and always expands to None + + => #doc doc + Help on function #doc in module hy.core.macros: + + #doc(symbol) + tag macro documentation + + Gets help for a tag macro function available in this module. + + def / setv ---------- diff --git a/hy/core/macros.hy b/hy/core/macros.hy index e9f9f6f24..acfd455f6 100644 --- a/hy/core/macros.hy +++ b/hy/core/macros.hy @@ -227,6 +227,7 @@ (deftag @ [expr] + "with-decorator tag macro" (setv decorators (cut expr None -1) fndef (get expr -1)) `(with-decorator ~@decorators ~fndef)) @@ -234,3 +235,41 @@ (defmacro comment [&rest body] "Ignores body and always expands to None" None) + +(defmacro doc [symbol] + "macro documentation + + Gets help for a macro function available in this module. + Use ``require`` to make other macros available. + + Use ``#doc foo`` instead for help with tag macro ``#foo``. + Use ``(help foo)`` instead for help with runtime objects." + `(try + (help (. (__import__ "hy") + macros + _hy_macros + [__name__] + ['~symbol])) + (except [KeyError] + (help (. (__import__ "hy") + macros + _hy_macros + [None] + ['~symbol]))))) + +(deftag doc [symbol] + "tag macro documentation + + Gets help for a tag macro function available in this module." + `(try + (help (. (__import__ "hy") + macros + _hy_tag + [__name__] + ['~symbol])) + (except [KeyError] + (help (. (__import__ "hy") + macros + _hy_tag + [None] + ['~symbol]))))) diff --git a/hy/macros.py b/hy/macros.py index 22bda2e8b..afa5da1eb 100644 --- a/hy/macros.py +++ b/hy/macros.py @@ -34,6 +34,7 @@ def macro(name): """ def _(fn): + fn.__name__ = "({})".format(name) try: argspec = getargspec(fn) fn._hy_macro_pass_compiler = argspec.keywords is not None @@ -63,6 +64,7 @@ def tag(name): """ def _(fn): + fn.__name__ = '#' + name module_name = fn.__module__ if module_name.startswith("hy.core"): module_name = None