Elixir: `@impl` documentation is not clear

[eksperimental]

reading the documentatation for @impl

  ### `@impl`

  To aid in the correct implementation of behaviours, you may optionally declare
  `@impl` for implemented callbacks of a behaviour. This makes callbacks
  explicit and can help you to catch errors in your code. The compiler will warn
  you if you mark a function as `@impl` when in fact it is not a callback, and
  vice-versa. It also helps with maintainability by making it clear to other
  developers that the function's purpose is to implement a callback.

What is the situation that it is exactly trying to describe by vice-versa?
does it mean that it will warn you when you don't add @impl to a call back? either case... it is not clear what vice-versa means and I suggest to explicitly mention it instead of using "vice-versa"

Sorry If it's just me, if not please somebody explain and I will submit a PR., thank you.

[fertapric]

does it mean that it will warn you when you don't add @impl to a call back?

I think it will warn you if other function was marked previously.

I agree that the docs can be improved. And maybe the docs should mention that it does not warn about missing @impl for overridable functions.

[josevalim]

@fertapric master does warn about overridable functions, iirc.

[josevalim]

What is the situation that it is exactly trying to describe by vice-versa?

It will warn if you mark a @impl when it is not a callback AND it will warn if it is a callback and you do not mark a @impl.

[fertapric]

It will warn if you mark a @impl when it is not a callback AND it will warn if it is a callback and you do not mark a @impl.

But it will warn only if another callback was marked before

@fertapric master does warn about overridable functions, iirc.

Here is what the test suite says:

• "does not warn for no @impl when overriding callback"
• "does not warn for overridable function missing @impl"

But, being honest, what I actually wanted to include in the documentation was this 😅:

• "warns only for non-generated functions in non-generated @impl"
• "warns only for generated functions in generated @impl"

[josevalim]

@fertapric perfect. :) Basically @impl is per context.

[eksperimental]

@fertapric Would you like to take care of this issue?

[fertapric]

I'm currently working on the warnings of #5800 🙂

Feel free to pick it (I think you will do a much better job than me 😅).

[whatyouhide]

I am tackling this.

[eksperimental]

Thank you @whatyouhide