I’ve been using ~S as a workaround for this and it appears to work well, though I’m not sure if there are side effects in terms of code bloat or performance at runtime.
~S"""
This is a long, long, long
multi-line comment.
"""
def foo
IO.inspect("You are awesome!", label: "Greatness: ")
end
There are no side effects or any bloat in performance in runtime. The only side effect is that compilation is slowed down for a few nanoseconds since compiler will instantiate this string
Why can’t doc private functions just for the owner? After all it’s not just a string, but connects tightly to intellisense and other functionalities to make development more convenient. For my self I’d love to hover my function and get a doc popup when I’m building a large system too complicated, so I can remember why I created this private function in the first place and how to use it. Docs should not only be user-targeted, but can also play an important role in development.
IIRC there’s a mechanical complication - the @doc annotations end up in :docs chunks in the compiled output BEAM files, but private functions aren’t guaranteed to compile to anything there (they may be inlined by the compiler).
If my logic gets significantly complex that there is a lot of stuff happening in private functions, I extract them to a @moduledoc false module. This signals that the module is “private” yet you can still @doc its functions, test them, and play with them in iex. However, even though @doc still works, I’m not sure that they will appear in IDE pop-ups (I’ve never actually tried that as I don’t use that feature). I guess it depends on at what stage the language server grabs the documentation.
Just do this:
@doc """
This is a thing where I can write docs and stuff.
""" && false
defp my_very_long_function(arg) do
end
Erlang 27 does support doc attribute for private functions as proposed by @josevalim. Does that means there was a shift of view I am unaware of or is Erlang different from Elixir in that regard?
Private functions #
The
-docattribute can be used for private function as well, so that tools and IDEs can provide docs if the user wants them to. However, the private function should not end up in the EEP 48 doc chunk
So 27 is released, we might see docs for private functions in Elixir now Erlang supports it natively. Let’s just wait for the next Elixir release and see if it includes it.
