add documentation macros

[gilch]

Closes #356.

This isn't exactly what was asked for, but we have three separate namespaces to deal with here--macros, tag macros, and runtime objects. It's entirely possible to have the same name in all three namespaces. Rather than trying to get help to work with all three somehow, this adds a doc macro for help with macros, and a #doc tag macro for help with tag macros. Using a macro to look up macros and a tag macro to look up tag macros seems easy to remember.

The other option would be to shadow the builtin help with a help macro. When passed a quoted symbol, it would look up the macro. When passed a keyword it would look up the tag macro with that name. When passed any other object, it would defer to Python's help. It seems a lot less intuitive though.

[Kodiologist]

What would you think of a help macro or function that asks for disambiguation if necessary? That is, it would recognize an ordinary value, a macro, or a tag macro, and if more than one of these existed, it would prompt you to choose one.

[gilch]

asks for disambiguation if necessary?

There might be a better approach, but that isn't it.

It seems like a pain compared to this version. Why make the user take a second step when they already know what they want? Printing off all three would be a better approach, but if the docstrings are long enough, that would make the user scroll back to find the right one, which is a second step again.

How do other Lisps handle this?

Common Lisp has it worse because it also has a separate function namespace. You have to remember to supply a second argument specifying which namespace to use, and you have to remember the valid names for the second argument, and you have to remember how to quote the object properly.

In Common Lisp, you should be able to use (documentation documentation) to see how it's done if you forget, but this is an error. You might then think that (documentation #'documentation) would work, but that's an error too. You have to remember the proper invocation is (documentation #'documentation T), in order to learn the proper invocation in the first place. Hy could do it this way, but I think it's a really bad design.

With my version, all you have to remember is doc--(doc doc) tells you how to use it and the other two---#doc, and help.

Clojure's doc doesn't have this problem, because you can't have a macro and a function with the same name in the same namespace. This is better, but Hy can't work like that if we want to be able to shadow macros with functions.

Not much help, but I'm open to more suggestions.

[Kodiologist]

Why make the user take a second step when they already know what they want?

For when the user doesn't. Functions and macros aren't visually distinct, and accepting #foo as a request for documentation on the tag macro foo seems useful for newbies. Asking for disambiguation also provides a useful warning of things sharing names when the user wasn't previously aware of this. If you also want users to be able to jump immediately to the one they want, you could have an optional second argument to indicate the type.

Printing off all three would be a better approach, but if the docstrings are long enough, that would make the user scroll back to find the right one, which is a second step again.

Right, and Python help strings can be very long (usually for classes, since every method's docstring appears when you call help on the class). So I recommend against this.

[gilch]

accepting #foo as a request for documentation on the tag macro foo seems useful for newbies.

Like (help #foo)? That's not going to work. Tag macros take precedence over even macros, so the compiler will try to expand it before help can get to it. Even quoting it like (help '#foo) doesn't work. The best you can do is (help "#foo") or #doc foo.

[Kodiologist]

True. (You'd think that would be more obvious to me given how much I've mucked about with lexing octothorpe stuff.) Allowing (help "#foo") makes sense. You could still get documentation for str or unicode with (help str) or (help unicode), assuming we're special-casing string literals.

[Kodiologist]

We could also go further and make the REPL treat lines beginning with help magically.

[tuturto]

Looks good, can you resolve conflicts still?

[gilch]

It was just the NEWS. We get conflicts in that a lot, but it's easy to fix.

This is probably just a stopgap until #1416. Then Python's help will work for everything.

[tuturto]

Eh, sorry. I should have looked into conflicts before asking you to resolve them.