Merge pull request #1415 from gilch/doc-macro

add documentation macros
This commit is contained in:
Tuukka Turto 2017-10-31 07:01:42 +02:00 committed by GitHub
commit 5975ad344d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 77 additions and 0 deletions

1
NEWS
View File

@ -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

View File

@ -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
----------

View File

@ -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])))))

View File

@ -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