Proposal: Introduce help catalogs

Let’s do it

I like the idea of the help catalog. I think it hits a good balance for beginner and experienced programmers alike.

I think it’s a worthwhile goal to make the catalog extensible and to avoid confusion by extending the functionality of help.

What are the help catalog functions supposed to do? Write to stdout or stderr? Return a string with the message? Is the message markdown formatted or does it use ANSI codes?

The help catalog to me feels like something that should be part of the documentation. This means that ExDoc should be able to compile a page that lists these and could be linked to. This may be partly achieved if we follow your implementation plan and include the catalog module in the documentation. However, since the actual content is an implementation detail of the functions we either loose that information in the docs or require an extra step while compiling docs of calling each of these functions and interpreting the output.

I wonder if we could make this part of the actual documentation. Two options I can think of:

1. make it part of documentation metadata on the module level:

defmodule Kernel do
  @moduledoc help_catalog: [
    nested_var: """
    Note variables defined inside `case`, `cond`, `fn`, ...
    """
  ]
end

In this case one could run elixir -h Kernel:nested_var or keep the help_catalog app entry part of the proposal and only change the lookup mechanics.

2. introduce a new module attribute @help_catalog keyword() with similar setup as in option 1. This would generate functions (probably with some special naming to avoid conflicts) with @doc(string). The main benefit of this is that now we don’t need any special handling of catalog entries on the client level. It can be just a simple help lookup and will work almost out of the box with ExDoc too.

Yes

In general all 3 proposals sound reasonable, while I personally don’t particularly care about 3. But I’m wondering if or how the catalog would deal with context specific text. I’m not sure if we have that in the current warning texts though.

Another question I have: Would it still be possible to have the current “verbose” warnings emitted by the compiler? I often just scroll through the list of compiler warnings and fix one after the other. Without having another window open it would be super tedious to lookup every unknown ones of those short warnings and even someone not new to elixir might not have all the useful help information in his head by just reading a short warning. Sometimes a good example makes you see a harder to catch typo or something like that. If the new help catalog would include even more help information than current warnings do this might be a lot of work to maintain (short / compiler / help catalog version).

Question 1: what do think about the idea of supporting help catalog in general? (regardless of the command structure, syntax, etc)

I see only benefits for this idea so yes.

Question 2: what do you think about the suggested syntax for catalogs and its implementation?

I agree with @lackac about including this in the docs somehow. I personally think that keeping it in a module is better as it does not clutter other modules with more attributes (it will start to look like Java with annotations all over the place).

A new section on docs would make this even more discoverable.

Question 3: should we close the gap and allow help and open generally available in the elixir and mix run commands?

Hell yeah!

If we stick to the implementation proposed by @josevalim we could have functions with an arity of 1 that take the version as argument (:short, :long, :detailed) and return the appropriate message. This would make it easy to maintain these from the same place. The compiler then could print :long for the first occurrence and :short for all the rest after that. In addition there could be command line flag to always print :short or :long.

Good question. The function will return a string in markdown, I have updated the document to mention it.

I thought about using regular documentation but I would like this to be dynamic. For example, if you invoke elixir -h elixir:guards, we could get Kernel’s documentation metadata and build a list from that programatically. So I think being at runtime gives us a bit more flexibility. We could still build a static list with ExDoc though. I think that’s a great idea!

We don’t have context specific text currently. It is something that we could do in the future but it is harder to do in Elixir in general because compiling code is the same as running code and, by then, some of the contextual information is already gone.

I like this idea but then it means we need to do another approach than the application based one. Doing the application lookup is ok for one-off script calls, such as elixir -h elixir:unused_var, but I wouldn’t rely on it for emitting warnings in general.

We could use an approach based on module names, but then I think the line gets very blurry between asking the documentation of a function (elixir -h Kernel.is_atom) and asking for a warning (elixir -h Kernel:unused_var).

EDIT: there is another issue with this approach. For the warnings themselves, you usually have some contextual information, such as the variable name that you skipped, for the detailed part, you wouldn’t have it anymore. So their APIs is not quite the same.

I don’t think it would be necessary to support returning :short and :long from the command line or the console. It would be useful enough to only return :detailed. In this case the code emitting the warning could rely on knowing the module name without looking it up.

Would it be too far fetched to add a second argument with opts \\ [] that makes this work? This could be later used to add contextual information to :detailed as well.

@josevalim I would like to comment also some parts of whole post, so:

When reading this something like that just screamed:

$ mix deps.compile
Note: some dependencies may not be up to date with latest Elixir changes which could produce extra warnings while compiling. Use `--silent-deps` to filter them when printing to standard output.

Note: It’s not proposition - just comment i.e. what comes to my mind when seeing it. If anyone is interested please create new topic and quote this part.

Heh, when reading your introduction and examples then I though just about something like that.

Definitely: YES

Hmm, personally for me more confusing is having all types of documentation and warnings explanation in one function.

h explain

                               def explain(code, app \\ :elixir)

    @spec explain(atom(), atom()) :: String.t()

Explains warning (…)

For me this looks enough clear, but others could disagree with me. In short this looks amazing, but for me it would be better separated.

This is awesome idea. To be honest I did not even tried to create any plug-in for any editor, but I think that it would be really helpful for plug-in developers.

Yes, please

EDIT

Just forgot one really useful case. @josevalim how you plan to display FunctionClausuleError? I think that in this case detailed information are really useful for everybody and shorten them could cause problems.

Ad. 1. I like the idea in general, but I also liked the long messages in the beginning with Elixir. It is extremely useful for beginners, and this (and great docs) is why Elixir is easier to learn than any other language.

On an very early stage of learning Elixir, if I try to reassign the value of variable, I will got the warning that the variable is unused:

iex(1)> a = 1
1
iex(2)> if true, do: a = 2
warning: variable "a" is unused (elixir --explain nested_var)

Imagine you’ve never seen Elixir or Erlang before. Isn’t it confusing? And it is perfectly explained with the long help. Yes, you can alway have a long explanation, but it is not available at the first sight. And not everyone would understand that it is possible to get the longer help message.

What if we do short messages optional? Like, by default, showing long messages (warning + help from the catalogue) and allow to turn on short messages by a switch --short-messages or an entry in .elixir?

Ad. 3. YES!

I have mixed feelings.

My concern is that by doing this it will reduce the helpfulness of the warnings. Often in the warning you can tell the user the code they should have written. But if that is moved and there’s no way to pass context to the help, then it becomes generic. For example, in one of the projects I work on I have this warning in a macro:

IO.warn("""
Calling assert_message_publish/1 with a message pattern is deprecated. Replace with:

    assert_message_publish #{inspect(binding()[:name])}, #{unquote(message_code)}

Or

    assert_message_publish #{inspect(binding()[:name])}
""")

In the case of this particular code, the user would have to do extra work to figure out what that first argument should be, whereas, I’m able to tell the user in the warning.

If this does get added, I’m not opposed to this approach. I would like IEx to print out the detailed warnings by default though.

If this does get added, yes. Also, could we have --help and -h with no args or some other flag to show the detailed version when running?