Merge pull request #1415 from gilch/doc-macro

add documentation macros

NEWS

@@ -24,6 +24,7 @@ Changes from 0.13.0
    * `while` loops may now contain an `else` clause, like `for` loops
    * `xi` from `hy.extra.anaphoric` is now the `#%` tag macro
    * `#%` works on any expression and has a new `&kwargs` parameter `%**`
+   * new `doc` macro and `#doc` tag macro
 
    [ Bug Fixes ]
    * Numeric literals are no longer parsed as symbols when followed by a dot

docs/language/api.rst

@@ -501,6 +501,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
 ----------
 

hy/core/macros.hy

@@ -232,6 +232,7 @@ Such 'o!' params are availible within `body` as the equivalent 'g!' symbol."
 
 
 (deftag @ [expr]
+  "with-decorator tag macro"
   (setv decorators (cut expr None -1)
         fndef (get expr -1))
   `(with-decorator ~@decorators ~fndef))
@@ -239,3 +240,41 @@ Such 'o!' params are availible within `body` as the equivalent 'g!' symbol."
 (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])))))

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__ = '#{}'.format(name)
         module_name = fn.__module__
         if module_name.startswith("hy.core"):
             module_name = None