Adding examples to error messages

[jefffriesen]

@bhb

The other day we talked about your ideas to add "did you mean..." examples to an error message by filling in the missing arguments based on the spec. I still think that's a great idea. Here is another cool approach that @oakes laid out in a gist: https://gist.github.com/oakes/8db57ac808bf6ec144d627fd83a89da3

It uses defexamples to show show an example of how a function can be used. (I appreciate his comment about how examples are especially helpful for non-English speakers).

Maybe if a defexample is defined for a function, you could show that after an expounded error message.

Better yet - show everything:

1. Show expound error message
2. Show their function with the corrected arguments. If you don't have enough information to reliable give them an example, don't show it. This could be collapsed by default in an IDE
3. Show the defexample if it's available. This could also be collapsed by default in an IDE

If the expound error message wasn't enough for me to figure out my problem, I would love to have multiple examples right there, in context, for me to figure it out. It would be nice to not be overwhelmed with information so it would be nice to optionally expand them with keybindings (or clicking in an IDE UI).

You could build this support directly into expound. Another direction could be that expound turns into a type of platform, where a user could install plugins such as defexemple or other things into it.

What do you think?

This ticket may be too broad - feel free to close it in favor of more specific tickets.

[bhb]

@jefffriesen It's a good idea! I do think examples would be really useful in this context, especially for beginners who may have less familiarity with the spec syntax.

This isn't well documented in Expound currently (hmm, maybe I need to use Dynadoc to document the API 😄 ), but it's possible to modify the default Expound printer, so any user could add extra info like the defexample to the output.

Unfortunately, right now the information that spec returns does not include the symbol of the function that was called, so there is no way to look up the example (which requires knowing the namespace and function name). The issue tracking this is https://dev.clojure.org/jira/browse/CLJ-2166 (please log in and vote for it! 😄 )

Once that fix makes it into Clojure spec, I will write up some example code of how to include examples defined via defexample. At some point in the future, I may include this by default, or at least as an option in Expound. I'm hesitant to add dependencies until it's clear that most users would like the functionality built in. Let's leave this issue open for now and see if it attracts upvotes 😄 .

[jefffriesen]

Sounds like a great plan.
(I've voted for that Jira issue 😄)

[marco-m]

FYI https://dev.clojure.org/jira/browse/CLJ-2166 has been resolved on 2018-06-26 and is available in clojure.spec release 0.2.168

[bhb]

Thanks again for the idea! Since I haven't seen a wide adoption of examples, I'm going to close this for now. If examples turn up in say, cljdoc and more people use them, I'd reconsider, but for now, I'm not inclined to add an additional dependency on expound.