Add __info__/0 function to modules

[alco]

We have __info__/1 added to each defined module. Two issues with it:

1. Nowhere in the code it documents which arguments the function supports.
2. Impossible to discover those arguments at runtime.

The function has similar intent to Erlang's module_info which is also added to each module.

I'm proposing to provide __info__/0 similar to module_info/0 that will return a list (or a keword list) of the things that can be retrieved using __info__/1.

[josevalim]

I don't want to pollute the module even further. So for now, I would like just to document properly what __info__ expects as keys.

[alco]

I don't think it's polluting. There is already __info__/1, and we don't want users to define __info__/0 in their code.

I'm thinking of adding a clause to the h helper that would redirect any h Whatever.__info__ to a single place where the doc for __info__ will be. That single place could be Module.__info__ stub so that we could extract the doc for __info__ from the already huge Module's moduledoc.

Having __info__/0 is simply logical. Users may not remember to look in Module for the doc of this function. h Whatever.__info__ will help with that, but having __info__/0 return the list of keys in addition to that is a plus, in my opinion.

Honestly, I would prefer __info__/0 to be defined as

lc key inlist supported_keys, do: { key, __MODULE__.__info__ key }

to be consistent with Erlang's module_info/0 since it's already superseding module_info, so we can get rid of module_info from the docs in favor of __info__.

[josevalim]

If the main use case is to get a list of keys, I am not sure if __info__/0 is the best option. I am not disagreeing with the problem, I just don't like the solution. Even more if we consider that __info__/0 would include the values, and just docs and moduledocs alone will generate a bunch of "garbage".

[alco]

The problem with large strings is solvable via pretty-printing. Erlang's shell truncates long strings by default.

In any case, what do you think about h AnyModule.__info__? I can pick Module's moduledoc and extract the part about __info__ from there. Or I could def __info__(option) inside Module and attach a @doc to that. I know you're not a fan of stubs, but I find this approach quite clean.

[josevalim]

👍 for the h(SomeModule.__info__) pointing to Module.__info__.