Elixir: Controlling documentation for automatically generated record macros

[whitfin]

Environment

• Elixir & Erlang versions (elixir --version): v1.5.2/OTP 20
• Operating system: macOS 10.12

Current behavior

If you create a record using defrecord, the generated macros are automatically added to your documentation:

my_record(args \\ [])
my_record(record, args)

It would be nice if there were some way to suppress the documentation. You could use defmacrop, but it's not always valid as you might want to use a record throughout a library and not expose the documentation for it. In addition, you might want to actually document what's valid in your records (beyond just a typespec), which doesn't appear to be possible either.

Is there some way these features could be added? Or are we just out of luck because of the macro generation?

[josevalim]

You can always add docs for something defined programatically by using bodyless clauses:

@doc "here are some docs"
def my_record(args)

@doc false
def my_record(record, args)

[whitfin]

@josevalim this does work (using defmacro instead of def) but doing so for the my_record(args) signature generates a warning in the compiler:

warning: definitions with multiple clauses and default values require a header.

Any ideas what I should do to satisfy this warning?

[ericmj]

@whitfin Can you show the code that produced the warning?

It's a bug if you get the warning when not defining default values or a function body. Im guessing it's happening because the record macros already defines a body-less function.

[whitfin]

Hi @ericmj!

Here's an example causing that warning:

defmodule Stuff do
  import Record

  defrecord :my_record, value: nil

  @doc false
  defmacro my_record(args)

  @doc false
  defmacro my_record(record, args)
end

And when I compile it from the command line, I see:

warning: definitions with multiple clauses and default values require a header. Instead of:

    def foo(:first_clause, b \\ :default) do ... end
    def foo(:second_clause, b) do ... end

one should write:

    def foo(a, b \\ :default)
    def foo(:first_clause, b) do ... end
    def foo(:second_clause, b) do ... end

defmacro my_record/1 has multiple clauses and defines defaults in one or more clauses
  test.ex:7

I discovered that you can actually suppress the docs with no warning doing the following, but it still feels like a bug:

defmodule Stuff do
  import Record

  @doc false
  defrecord :my_record, value: nil

  @doc false
  defmacro my_record(record, args)
end

[ericmj]

We shouldn't warn about multiple clauses with default values when we are defining a function head since it doesn't have a clause.

[ggcampinho]

I will try this one!

[josevalim]

Closing in favor of the PR.