This is another good point. Tooling picks up the @doc tags for functions, but doesn’t for regular comments.
jeramyRR
jeramyRR
Perhaps all of us are just looking at this the wrong way completely. Jose pointed out that the @doc attribute is like python’s docstrings. It’s a quick way to get documentation printed out, and you can run a parser to find example strings for tests. It is however lacking the power that the documentation/commenting systems of languages like Java and C# provide out of the box.
I tend to like strong, statically typed languages like Rust and C#, where a lot of what’s going on can be gleamed from the inputs to a function and it’s return type. To get anything close to that I need to use Dialyzer. Without Dialyzer I comment my functions more heavily than I would otherwise. I still comment them while using Dialyzer, I just don’t have to add what’s expected to go into and out of the function.
Let’s take the function below for example:
defp build_url(%{ url_params: params }) do
...
end
From that I can gleam that I’m taking in a map or struct that has url_params as a field. Yeah that’s great and simple, but really what I want devs coming after me to know is that we are using a Request struct in the pipeline. I know, I know, the function doesn’t have to take in a specific type and that’s all we really need, but is that really enough?
I could define it the longer way:
defp build_url(request) do
url_params = Map.get(request, :url_params)
...
end
No, that’s not right either. What I really want to do is:
@doc """
Description: Using the url_params field from a Request struct, we build ... blah
Consider: Note that this function may create a string that is not url friendly if
the params provided have any of the following characters:
< > # % { } | \ ^ ~ [ ] `.
To guarantee a url friendly string, filter the params through the
filter_url_params function first.
Example:
url_string = %Request{ url_params: [ "comp": "list", "max_items": 40 ] }
|> filter_url_params
|> build_url
Param: a Request struct
Return: A string that may or may not be url friendly.
"""
defp build_url(%{url_params: url_params}) do
...
end
I don’t need a nice pretty web page created from that, but it is really helpful when the tools like VS Code or Intellij pick it up. They don’t/won’t do that with # comments.
1
josevalim
Creator of Elixir
In that case, I would either surface it to the documentation of the parent function (the one that calls build_url), or move it to its own public function so I can properly document and test it.
For example, you could mention in the public function that any parameter containing < > # % { } | \ ^ ~ [ ] will be filtered out before building the URL. It may help you focus on the behaviour of the code instead of focusing on the implementation. But I can’t say for sure, I have only part of the context.
0
simon
I’m sure this has probably been raised (and rejected) before but what might make commenting ‘easier’ and therefore as appealing as multi-line @doc blocks would be support for multi-line comments; something like /# and #/ perhaps.
1
josevalim
Creator of Elixir
The behaviour could be changed to discard @doc but I think allowing @doc in privates would open up a bunch of other problems. For example, if you try to write a doctest, it won’t work, because you can’t invoke a private function. Oh, do you want to access the @doc in your editor or terminal? That won’t work either, because private functions do not necessarily exist after the module is compiled, they can be inlined, transformed or even fully removed. Allowing @doc would indicate that those two constructs (public and private functions) are somewhat at the same level while they quite clearly aren’t.
All of this has already been said, so I will politely bow out of the discussion as I don’t have anything new to add here. 
12
OvermindDL1
I like @doc’s because it appears in my IDE when using a function call, comments do not (plus you can’t be sure what a ‘comment’ is attaching to unlike a @doc. Even when using private functions that detail some complex algorithm and what this specific part is doing is amazingly useful. I do # comment those currently but I get no intellisense about that where I would if it were @doc.
6
cohawk
I agree with the request for a multi line comment format. I currently just keep the doc blocks for private functions and ignore the compiler warnings since I like the IDE color formatting and don’t like the looks of:
_ = “””
Comment block
“””
2
mguimas
I have done the same private documentation style, but feels inconsistent to me.
There will be no general agreed solution for this in the Elixir community. No language has everything that everybody wants, sorry!
Move on.
0
mattste
I’d love to see an @docp that supports the same syntax as @doc but does not generate documentation (or runs doc tests). An alternative could be to allow a way to allowlist the warnings that come up when a module attribute is unused.
Proper multiline comment support before function heads would be a workaround. My current approach is the one outlined here. The issue is the autoformatter adds a newline and function parenthesis.
comment("""
Here is a multiline comment.
Here is a multiline comment.
""")
defp my_func()
4