Ex_doc: Setting @doc to false and with documentation

[thojanssens]

Say I have documentation for a function:

@doc ~S"""
This is really an awesome function.
"""

I don't want to add it in the docs for now, so I want to set @doc to false, but I also do not want to lose the documentation already written so far. So I write something like:

@doc ~S"""
This is really an awesome function.
"""
@doc false

But now this will generate a compile warning:

warning: redefining @doc attribute previously set at line 90
lib/foo/foo.ex:93: Foo (module)

[josevalim]

You can do this:

@doc ~S"""
This is really an awesome function.
""" && false

We want to keep the warning because sometimes people accidentally @doc false the wrong function.

[thojanssens]

FYI mix format doesn't work well with this syntax; it will indent like this:

  @doc ~S"""
       This is really an awesome function.
       """ && false
  def my_awesome_function() do

The documentation text and the last @doc line are aligned to the ~ character of the sigil ~S.
As soon as I remove && false and run mix format, the indentation gets back to normal.

I use mix format extensively so I have now to check constantly that I do not commit with this weird indentation, and fix the indentation.

[wojtekmach]

As a workaround, I'd consider turning @doc ... into comments, or comment them out:

# @doc """
# ...
# """

[eksperimental]

can't you just do @_doc ~S""", or do @doc_false, or comment the whole thing out?

[thojanssens]

can't you just do @_doc ~S""", or do @doc_false, or comment the whole thing out?

:satisfied: I didn't think about just changing the attribute's name

[thojanssens]

@eksperimental
@_doc or other attribute name will generate a warning, so it's not a viable solution:

warning: module attribute @_doc was set but never used

@doc ~S""" [...] && false will mess up the formatting with mix format.

The best solution is then to comment it out as @wojtekmach suggested.