What is the specific syntax of @derive module attribute and where is it documented explicitly?


(I also asked on Stackoverflow, I hope cross-posting is ok.)

I expected it to be documented in Module, probably with references to structs, but no joy. Seen it used with a single or a list of arguments. All the variations I could find so far:

The only places I found mentions of @derive:

Wasn’t sure whether I’m not just overlooking something, therefore didn’t open an issue or pull request.


Its documented in Kernel.defstruct/1.

This has bugged me for a while too. The docs @NobbZ pointed to say:

Yet there are non-confirming examples that clearly work but aren’t documented anywhere I can see either. Like in Poison:

defmodule PersonOnlyName do
  @derive {Poison.Encoder, only: [:name]}
  defstruct [:name, :age]

defmodule PersonWithoutName do
  @derive {Poison.Encoder, except: [:name]}
  defstruct [:name, :age]

Clearly not a list of modules either! The docs for Protocol give some clarity to what is actually going on under the hood.

And indeed, for Poison, the implementation follows this mechanism.

I think this is one part of the docs that could be improved (I wonder if its on @eksperimental’s list of planned improvements).