Elixir: Function `__info__/1` is referenced in the docs but not documented

[mguimas]

Environment

• Elixir 1.7.3

Current behavior

Function __info__/1 is referenced in the Module docs but it is not documented.

Expected behavior

Provide documentation for the __info__/1 function, or a link to somewhere it is documented.

[mguimas]

Probably it is worthwhile to also document that every module has a module_info/0,1 function too, and describe how it is different from __info__/1.

[josevalim]

It is documented here but it is not making it to the docs chunk in BEAM: https://github.com/elixir-lang/elixir/blob/master/lib/elixir/lib/module.ex#L496-L516

Not sure if it should make it to the chunk though. What do people think?

[mguimas]

Unfortunately I do not know about BEAM chunks, nevertheless the documentation for __info__/1 should somehow appear in the docs. Thanks.

[mguimas]

I even think that the documentation for all exported symbols in a module, whether generated or not, should appear in the docs.

The idea is: if something in a module is callable from the outside then it should be documented.

Thanks.

[michalmuskala]

The documentation of a module, in general, documents the public API for consumers to use, there might be a lot of functions that are callable and that are not documented (done by using @doc false). __info__/1, module_info/0,1 and behaviour_info/1 are sort of a metadata and I don't think documenting them on every single module would be useful - they would be just noise in the documentation and would be distracting instead of helpful. If you read the documentation once, it would never change. Furthermore, the return value of some of the callbacks (module_info in particular) depends on the VM you're running the code on and differs between OTP releases, so it's difficult to document it in a uniform way.

We should definitely document somewhere that those "default functions" exist and maybe what they do (probably in the Module module), but I don't think doing anything more would be helpful.

[josevalim]

@michalmuskala I am thinking that, because __info__/1 is actually callable, we should go ahead and add it to the chunk as well, so it appears as __info__. FWIW, this was used to happen, but it probably got lost at some point.

[michalmuskala]

One option could be to document all those functions as callbacks in the Module module, then we could link them nicely.

[mguimas]

I agree with functions common to all modules to be fully documented in Module.

Regarding:

... the return value of some of the callbacks (module_info in particular) depends on the VM you're running the code on and differs between OTP releases, so it's difficult ...

I suggest that these cases should also be documented, highlighting the dependency on the VM, but also giving an example of what the return value might be. I don't know if this is possible, but the return value could be computed for the VM in which the documentation is being generated, thus providing an updated example always the docs are generated.

[eksperimental]

@michalmuskala I am thinking that, because __info__/1 is actually callable, we should go ahead and add it to the chunk as well, so it appears as __info__. FWIW, this was used to happen, but it probably got lost at some point.

Yes, I remember reading about it.
It got lost in v1.7 probably with the new fetch_docs function