Documentation should be stored in the beam files

[josevalim]

Reference: https://github.com/nox/otp/blob/rm-reverse-eta-conversion/erts/preloaded/src/add_abstract_code

[krestenkrab]

Do you intend to add an extra section to the beam files, or just add another function ala __info__ / module_info that returns the appropriate documentation? I think the latter makes most sense; but it depends on what you want to achieve.

[josevalim]

We need to add an extra section. Today all documentation is loaded and added to the literal pool when the module is loaded. By moving to chunks, we can load it only when needed.

José Valimwww.plataformatec.com.br http://www.plataformatec.com.br/Founder and Lead Developer

[krestenkrab]

OK; that sounds good.

[alco]

Doesn't look like the beam_lib module supports user-defined chunks. So I guess you meant hacking Erlang to add a predefined chunk for docs. Should we raise a question on the ML first?

[josevalim]

@alco the example in the description shows how to gather BEAM chunks to build a module to attach docs. Why would we need to raise a ML question first?

[alco]

The example shows how to replace the contents of the "Abst" chunk with something else and write it back to disk, right?

This chunk is already reserved for debug info. In that branch the beam file in question is written in Erlang assembly and the "Abst" chunk is manually written to store abstract code of a stub module written in Erlang.

Elixir modules already have "Abst" chunks with contents written by compiler. Therefore I'm worried whether replacing that contents is guaranteed to work as we expect.

What I was saying previously is that each chunk type is used in some way by the Erlang compiler or the run time system and it seems there is no way to add user chunks that will not be touched by either.

Am I missing something?

[josevalim]

We should just define a new chunk name and store there, like ExModDoc and ExDocs.

José Valimwww.plataformatec.com.br http://www.plataformatec.com.br/Founder and Lead Developer

[alco]

This is what I was referring too. We need to modify beam_lib for that: https://github.com/erlang/otp/blob/07b8f441ca711f9812fad9e9115bab3c3aa92f79/lib/stdlib/src/beam_lib.erl#L684

[josevalim]

Hrm, let's ping @nox.

José Valimwww.plataformatec.com.br http://www.plataformatec.com.br/Founder and Lead Developer

[nox]

Hello. What is this Elixir thing you people are talking about?

You can see in beam_lib that the atom chunk names are just for convenience, a 4-byte code can also be used, see chunk_name_to_id/2 for the default 4-char codes.

[josevalim]

Elixir is a book by Hillary Duff and one of the chapters contain a Swedish Beans recipe. We have decided to give this BEAN VM a try as we have heard good things about it but we are struggling with the recipe files.

Thanks for your help @nox! Please send me your email if you would like a free copy of the book!

José Valimwww.plataformatec.com.br http://www.plataformatec.com.br/Founder and Lead Developer

[nox]

You're welcome. I can't wait to receive it. Send it at nox@homoiconic.ly.

[bitwalker]

So disappointed that domain doesn't actually exist.

[alco]

How can we be sure someone else doesn't sneakily add a chunk with the same name we choose?

[nox]

How can you be sure someone else doesn't sneakily sends a message to a process? Sneakily inserts a value in an ETS table?

[krestenkrab]

Only sufficiently intoxicated (or elixirized) people would be crazy enough to add chunks to beam files generated by the elixir compiler. I'd find something else to worry about.