Just as a note, I love this! Never let warnings be disableable! 
/me wonders if there is a way to pass the warnings_as_errors flag in mix.exs…
Overall though, I like the verbose warnings. It is both telling you what is wrong and often how to fix it, but also is a big thing of “You Need To Stop Doing This Warning Thing”.
But a help catalog could be quite, just as long as the big warnings by default don’t stop.
Honestly… Yes by default, it makes it far less ignorable!
Q1
A help catalog with a more detailed information about the warning would be a great addition.
Q2
Making help and warning info accessible via the elixir command would be another great addition.
Q3
This would be the natural progression of 2, so I vote for this too.
One suggestion I have is to not restrict the help catalog to just warnings. It would be great if we could expose other kinds of useful information which is usually shoved into a README or Getting Started guide via the help catalog. Take distillery for example, it would be great if we could list all the topics in a help catalog for distillery by something like elixir -h 'distillery:*' and then get detailed info on elixir -h distillery:getting_started or elixir -h distillery:phoenix.
This is a potential source of confusion but I don’t believe the catalog would work as a general pages or guides. I don’t believe the command line is a rich enough environment for such material.
We may use URLs and point them to an online version hosted at elixir-lang.org. Sure, this may add some burden when releasing Elixir and making sure there’s a new help catalog online, but nothing beats URLs at being easy to access.
Still not sure with lib’s catalog though. 
I think we should be able to integrate the catalog with ExDoc, which means both Elixir and libraries should have online versions of those. But I’d personally prefer a flow that works on the command line (or from my editor) and does not require a browser. Thoughts?
I think this is a good enough reason to go with the functions based approach that you’re proposing.
This got me thinking. Isn’t accessing the catalog with help placing it in the same frame of reference from the perspective of the user as documentation and guides? We’re even calling it help catalog, but the purpose seems to be limited to explaining warnings and errors in more detail. I don’t think it should work as a general pages or guides collection either, but in that case we should probably go with a different name that clearly defines the purpose. I think we should also reconsider --explain.
Regarding naming, I don’t like the sound of “error catalog” or “warning catalog”, so I did a quick thesaurus lookup on “warning” and these jumped out at me: notice, advice, advisory, hint. I like the sound of “advice” or “hint” and think that they communicate the purpose better. elixir --hint elixir:nested_var? I think this also helps newcomers understand what this command means in a warning message.
The only issue I have with the above is that it moves this farther from documentation as the storage and retrieval mechanism. On one hand we can use this information to compile a list of hints (just trying to see how it sounds) in ExDoc. That makes it useful to Elixir core and libraries. We could then solidify the convention, and popularise it in other Erlang VM languages to let them benefit as well. Or we could rely on the docs chunk which is already making its way into those languages. It seems though that the docs chunk approach would prevent dynamic content. Isn’t there a way to have the best of both worlds? I have a half baked solution in mind, but will sleep on it before I write it up.
I’m totally pro having shorter warnings for stuff like unused variable x, but having an easy way for newcomers to get more info about it. But like @lackac, I’m not so sure about the naming after reading all the discussion. So not so sure, if I like the overall idea of a separated feature for it.
Good enough. But:
Yes, sure.
Now, with my considerations for each question in mind, what about doing something like:
defmodule Foo do
@moduledoc "Foo doc"
@doc """
Foo.bar doc
# Warnings
## Put some warning title here
And its description.
## Put another warning title here
And more description.
"""
def bar do
...
end
end
And of course, elixir -h app:Foo.bar would totally do the job, you should only link to them on the documentation.
If one would like to separate warnings, like you want to do to core, it’s always an option to create a warning function like:
defmodule Foo do
@moduledoc "Foo doc"
@doc """
Foo.bar doc.
Please notice this function can throw `warning1` and `warning2`.
"""
def bar do
...
end
@doc """
# Warning title here
And its description.
"""
def warning1, do: warn("this")
@doc """
# Another warning title here
And more description.
"""
def warning2, do: warn("that")
end
PS.: for warnings thrown by erlang code, you could create a CompilationWarnings module with the functions and docs for each of them and raise an exception if they are called directly.
This would use the stuff we already have, so no complexity added to the core, and it is a very plausible solution for the problem you have IMO. And with this solution in mind, my final answers to the questions would change to:
elixir and mix run commands?So what do you think?
Being able to access documentation directly from IEx is useful to me. It allows me to not get stuck on a problem while coding when I have no internet access (and also access from the terminal is just quicker and more convenient IMO). I would not like to see an error message, which I don’t fully understand, and then have to rely on internet access to view the detailed description.
We need to balance the confusion of also using help for catalog with the confusion of introducing a third option. Today we already have two commands: help and info. I don’t know the correct answer, but I have a feeling introducing a third command will just be too confusing.
To be very fair, there is nothing stopping someone from adding “distillery:phoenix”. Elixir will have a “elixir:guards” and we do have a page named “Guards”. Implementation wise you could just File.read!(...) the page contents. I just wouldn’t expect packages to necessarily do this because pages just look superior on ExDoc thanks to navigation, accessibility tools, hopefully search, etc.
I have mentioned on other replies why I don’t think moving this to the documentation is a good idea, so please check them and follow back. But in a nutshell, there is more dynamic information than just the context of the warning.
“Yes” to all the questions.
I really like how Credo does this: shows you one-liners with an option to print a very detailed information about each one. My only gripe is that one needs to copy-paste the whole location (filename + line number) into the command line to get the details. It would be better to just number the warning so that it’s easier to type in the command that prints the explanation for a specific occurrence. I’d also rather have the hint about --explain appear only once. Summing up, something along the lines of:
Compiling 1 file (.ex)
warning #1: variable "thing" is unused
lib/file.ex:8
warning #2: function MyModule.next/1 is undefined or private. Did you mean one of:
* next/2
lib/other.ex:98
Compilation finished with warnings. Use "mix explain" to get a detailed explanation or "mix explain #2" to explain a specific warning.
As for the short/medium/long thing, I would like something like the following rule: by default print the “what”, “where” and contextual hints for fixing; put the “why” and general hints/explanation in the catalog. In the example above, I’d rather have the notice about prefixing the variable with _ in the catalog since an unused variable might be because of a typo or incomplete refactoring. On the other hand, I’d like to keep the suggestions for the second error since this is useful for fixing the problem.
I find myself doing the same. My only concern is: how/will this work for deps? It would make sense to put it in the context of Mix, so something like mix explain app:entry.