31

Most languages allow block comments, and multiline commands.

For example, a multiline comment in HTML looks like the following: 

<!-- 
Warning, brave programmer:
Here be dragons.
-->

In Elixir, the closest thing I have found comes from EEx (docs).

EEx smartengine <% #comments %> seem to be discarded from source, even if they are multiline. However, this is just a workaround.

Does Elixir have a multiline comment feature, or a way to instruct the compiler to discard text from the compiled .beam file?

s3cur3
  • 2,749
  • 2
  • 27
  • 42
Nathan Basanese
  • 8,475
  • 10
  • 37
  • 66

5 Answers5

31

Elixir does not have multiline comments.

However, one very common use case for multiline comments is documenting modules and functions, for which you can use the module attributes @doc and @moduledoc together with heredocs.

defmodule MyModule do
  @moduledoc """
  This module is great at X
  """

  @doc """
  Frobnicates the given string.
  """
  def frobnicate(s) do
  end
end
Nathan Basanese
  • 8,475
  • 10
  • 37
  • 66
Patrick Oscity
  • 53,604
  • 17
  • 144
  • 168
  • 1
    // , Actually, I didn't want to put this in the question since I get accused of being long winded a lot, but I'm trying to convert my projects over to the Literate Programming technique. I'm told I have a rather odd way of going about things, and I will not be the one maintaining my project. A sort of intermediate step in this conversion will, I suspect, involve massive strings that I would rather not have end up in my `.beam`s. Do the `@moduledoc` and `@doc` end up in compiled code? Do Literate Programming tools exist that use Elixir-lang? – Nathan Basanese Jun 10 '15 at 07:16
  • // , Maybe I should ask these as separate stackoverflow.com questions. – Nathan Basanese Jun 10 '15 at 07:21
  • Yes, the module attributes end up in the beam file, so we can look up documentation for a module in iex, for example. I am not aware of literate programming tools for elixir, but that obiously doesn't mean they don't exist. Are you sure the comments end up in the BEAM file? I think they should be discarded. – Patrick Oscity Jun 10 '15 at 07:51
  • 1
    I need to clarify the thing with module attributes: "normal" module attributes do _not_ end up in the BEAM file. The special ones listed in the documentation also are discarded, but they are used to generate documentation, which in turn ends up in the BEAM file. – Patrick Oscity Jun 10 '15 at 07:54
  • // , As to "Are you sure the comments end up in the BEAM file?", did I imply that I thought that comments were ending up in the BEAM file? Also, I think I like the sound of that "'normal' module attributes do not end up in the BEAM file." bit. Could that be a way to make multi-liners that the compiler discards? Am I edging into bad programming practices, here? I don't want to teach the little chickadees bad habits. – Nathan Basanese Jun 10 '15 at 08:00
  • 1
    I think using module attributes to do literate programming feels wrong. I am quite sure that comments do not end up in the BEAM file, they are discarded by the tokenizer. See this recent question: http://stackoverflow.com/questions/30543321/is-that-possible-to-get-comments-with-macro – Patrick Oscity Jun 10 '15 at 08:06
  • Let us [continue this discussion in chat](http://chat.stackoverflow.com/rooms/80142/discussion-between-37coins-and-patrick-oscity). – Nathan Basanese Jun 10 '15 at 08:11
  • 8
    There is some confusion here. The documentation is stored in the BEAM file but it is not loaded when the module code is loaded. It is stored in a special chunk, which is loaded only when needed, similar to how the abstract code is stored. Other than that, attributes aren't stored in the BEAM file too, unless explicitly configured. – José Valim Jun 10 '15 at 13:29
  • 2
    You'll probably want to use `@moduledoc ~S"""` and `@doc ~S"""` to avoid interpolation. – Michael Johnston Jan 05 '16 at 20:14
  • // , Accepted for clear and direct **Elixir does not have multiline comments.** at the top, and for the exemplary levels of scrubious frobnication. – Nathan Basanese Aug 06 '18 at 18:12
16

I try to just use """ to quickly comment code a la Python, without turning it into a documentation

"""
def some_function() do
  some_code    
end
"""
owyongsk
  • 2,349
  • 1
  • 19
  • 21
13

Macros could help here to some degree:

defmodule Comment do
  defmacro comment(_text) do
  end
end

defmodule TestComment do
  import Comment

  comment """
  Module
  Comment
  """

  def func do
    comment """
    Function
    Comment
    """
  end
end
Dimagog
  • 1,785
  • 19
  • 14
  • // , This does not seem as 'proper' an answer as using the `@moduledoc` and `@doc`, but it answers the specific question more directly. – Nathan Basanese Feb 16 '16 at 00:02
  • // , Would this text be present in the BEAM file? – Nathan Basanese Feb 16 '16 at 00:03
  • 4
    @NathanBasanese: the text is discarded by the macro, so it won't even be in the AST after macro processing. So no, it will not make it into the BEAM file. – Dimagog Dec 16 '16 at 20:42
  • // , Given that this will not end up in the `.beam` file, I'm liking this answer a bit more. For the curious, "AST" in the above comment refers to an "Abstract Syntax Tree". You can search in the page at the following link for Abstract Syntax Tree for a good bit of context beyond the generic WikiPedia article. #nocsdegree – Nathan Basanese Dec 17 '16 at 05:16
  • 2
    `docp` and `doc` generate warnings by the compiler. I think this is by far the best solution. It's just not standard practice. – Christophe De Troyer Feb 02 '17 at 15:32
7

You can simply use module attributes for multiline comments, no macro required. I typically use the following for documenting/commenting private functions:

@docp """
This is my
multi line
comment
"""
Kip
  • 684
  • 5
  • 8
  • 1
    This has to be the absolutely simplest and cleanest way of doing multiline comments! – Anders Hansson Feb 04 '17 at 09:03
  • 3
    `warning: module attribute @docp was set but never used` – Kamil Lelonek Jun 23 '17 at 08:10
  • Yes, you're right. I think that started in Elixir 1.4.x so I no longer use that strategy for the same reason. I'm back to mostly using comments. Although in a few cases I have actually created a macro called `docp` that compiles to nothing. – Kip Jun 24 '17 at 09:09
  • 2
    How about just """ without the @docp? – owyongsk Sep 05 '17 at 05:58
0

I know I'm late and that this question has already been answered, but I found a way that works, using a sigil that prevents string interpolation. I figured I could share it for others who stumble upon this post.

~S"""
Hi! 
I'm a
multiline comment!
"""

This works in modules and functions too, including if it is the last thing in the block. Unlike regular string literals (i.e. without the ~s sigil prepended to it), this does not throw an error or warning.

Keep in mind that this is not an official language feature. Out of the box, Elixir only supports single-line comments (# Comment) and the module documentation syntax (@moduledoc / @doc).

TheWitheredStriker
  • 21
  • 5