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

[toraritte]

Hi,

(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:

• list of module names such as
  @derive [MyProtocol, Another]

  (e.g., Kernel.defstruct/1 macro doc,
  line 65 in ProtocolTest (v1.7.4))

• module name such as
  @derive Inspect

• tuple in the form of
  @derive {Protocol, key1: :val1, :others}

  (e.g., line 550 in InspectTest (v1.8.0-rc.0),
  Phoenix.Param protocol doc)

• list of tuples such as
  @derive [{Prot1, :options}, {Prot2, key: :val}]

  (e.g., line 225 in ProtocolTest (v1.7.4))

The only places I found mentions of @derive:

• “Deriving” section in the documentation of Kernel.defstruct/1 macro
• New (i.e., v1.8.0-rc.0) “Deriving” section of Inspect
• Documentation of Protocol.derive/3 macro (added in #7019)
  (This was extremely helpful because using the example snippets one can test all the combinations above.)

---

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

[NobbZ]

Its documented in Kernel.defstruct/1.

[kip]

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

This can be done by defining a @derive attribute as a list before invoking defstruct/1 :

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]
end

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

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).