Is it necessary to warn about the @doc attribute for a private function

Chat / Discussions
,
42

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()
3 Likes
43

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
4 Likes
44

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

1 Like
45

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.

5 Likes
46

You can, but with
#
instead of
@doc

1 Like
47

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).

48

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.

2 Likes
49

Just do this:

@doc """
This is a thing where I can write docs and stuff.
""" && false
defp my_very_long_function(arg) do
end
6 Likes
50

Honestly, I never had a clue you could do this.

8 Likes
51

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 -doc attribute 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

1 Like