From 91bdaea53502dc2ca1d06e03ffbfd2fc5aa7e89c Mon Sep 17 00:00:00 2001
From: gilch <gilch@users.noreply.github.com>
Date: Thu, 7 Sep 2017 12:57:19 -0600
Subject: [PATCH] add documentation macros

---
 NEWS                  |  1 +
 docs/language/api.rst | 35 +++++++++++++++++++++++++++++++++++
 hy/core/macros.hy     | 39 +++++++++++++++++++++++++++++++++++++++
 hy/macros.py          |  2 ++
 4 files changed, 77 insertions(+)

diff --git a/NEWS b/NEWS
index 4be51d4..15ae2ed 100644
--- a/NEWS
+++ b/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
diff --git a/docs/language/api.rst b/docs/language/api.rst
index 2f5511e..63102c8 100644
--- a/docs/language/api.rst
+++ b/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
 ----------
 
diff --git a/hy/core/macros.hy b/hy/core/macros.hy
index d8ee145..987e92e 100644
--- a/hy/core/macros.hy
+++ b/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])))))
diff --git a/hy/macros.py b/hy/macros.py
index 22bda2e..fe22d1d 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__ = '#{}'.format(name)
         module_name = fn.__module__
         if module_name.startswith("hy.core"):
             module_name = None