Annotate @doc metadata when a function is inlined

[fertapric]

I've seen the documentation of some functions contains "Inlined by the compiler" and I thought it would be a nice addition to include that information in the @doc metadata.

I was going to ask first in the mailing list, but the changes were quite straightforward and I decided to give it a go :)

[josevalim]

I am not so sure because the :inline mechanism is something very specific to Elixir and only in the modules in the standard library. So even if we go with something like this, I think we would need a more specific key. But I am more inclined to go with a no. -- *José Valim* www.plataformatec.com.br Skype: jv.ptec Founder and Director of R&D

[fertapric]

Right. I did not think about other languages running on the Erlang VM.

[whatyouhide]

@fertapric it's not just about other languages, I would say it's mostly about the fact that we only inline in Elixir code, so code written in Elixir and using ExDoc would not be able to use :inline.

Personally, I don't think we gain a lot by having this in ExDoc as it feels we're basically moving the line that says "Inlined by the compiler" from the docs to a doc attribute without making use of the doc attribute in any meaningful way (other than displaying it on ExDoc, which is already achieved by putting it in the docs though). So for me it's 👎 as well.

[fertapric]

@fertapric it's not just about other languages, I would say it's mostly about the fact that we only inline in Elixir code, so code written in Elixir and using ExDoc would not be able to use :inline.

I was thinking in letting developers use @doc inline: true when they use @compile {:inline, some_fun: 2, other_fun: 3}. Here is an example outside the Elixir codebase.

The main goal of this flag would be to standardize how Elixir functions are marked when they are inlined. Right now, if developers want to express that, they need to follow the convention established in this sentence of the Kernel docs:

Those functions will be explicitly marked in their docs as "inlined by the compiler".

But I don't have a strong opinion on this. So, if you are not 100% sure about this PR, I think it's better to close it. It's always easier to add than to remove :)

[josevalim]

The @compile :inline flag is very different from the inlines behavior we are describing here. In particular, the flag has no behavior for callers outside of the module. -- *José Valimwww.plataformatec.com.br <http://www.plataformatec.com.br/>Founder and Director of R&D*

[fertapric]

In particular, the flag has no behavior for callers outside of the module.

I did not know that 😅

The @compile :inline flag is very different from the inlines behavior we are describing here

I guess the list of "Inlined by the compiler" functions is this one.

One question: the functions of the Map module that appear on the list of functions "Inlined by the compiler" are Map.keys/1, Map.merge/2, Map.size/1, Map.to_list/1, and Map.values/1, but the functions Map.has_key?/2, Map.fetch/2, Map.fetch!/2, Map.replace!/3, Map.put/3, and Map.delete/2 state in their documentation that they are "Inlined by the compiler", is that correct?

[fertapric]

Nevermind. I see they are rewritten here.