Silence compiiler warning about @doc on private functions

TL;DR It's not possible to silence compiler warnings about @doc for private functions

Reasoning behind it:

Elixir treats documentation and code comments as different concepts. Documentation is an explicit contract between you and users of your Application Programming Interface (API), be them third-party developers, co-workers, or your future self. Modules and functions must always be documented if they are part of your API.

Code comments are aimed at developers reading the code. They are useful for marking improvements, leaving notes (for example, why you had to resort to a workaround due to a bug in a library), and so forth. They are tied to the source code: you can completely rewrite a function and remove all existing code comments, and it will continue to behave the same, with no change to either its behaviour or its documentation.

Because private functions cannot be accessed externally, Elixir will warn if a private function has a @doc attribute and will discard its content. However, you can add code comments to private functions, as with any other piece of code, and we recommend developers to do so whenever they believe it will add relevant information to the readers and maintainers of such code.

Source: https://hexdocs.pm/elixir/writing-documentation.html#documentation-code-comments


There is no way to silence compiler warnings.

In the past, people have asked about documenting private functions for use with ExDoc or DocTest. However, this not possible. Per José:

It is worth remembering that a private function does not exist outside of the module that defines it. You cannot test private functions because you can't invoke a private function outside of the module that defines it.

In fact, the compiler may even remove the private function entirely during compilation. This means a private function only exists when looking at the code and, if you need to look at the code to read it, then it is not documentation.

A private function is, for all purposes, exactly what you defined code comments to be: a temporary or semi-permanent blob which is aimed directly at developers. There is no guarantee it will exist tomorrow, which is why it is private.

Tags:

Elixir