Document @impl true automatically sets @doc false

Closes #7505.

1 files changed, 7 insertions, 2 deletions

diff --git a/lib/elixir/lib/module.ex b/lib/elixir/lib/module.ex
index a38d4dc13..1270706f7 100644
--- a/lib/elixir/lib/module.ex
+++ b/lib/elixir/lib/module.ex
@@ -57,9 +57,9 @@ defmodule Module do
 
   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
+  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
+  vice-versa. It also helps with maintainability by making it clear to other
   developers that the function's purpose is to implement a callback.
 
   Using `@impl` the example above can be rewritten as:
@@ -87,6 +87,11 @@ defmodule Module do
         def baz(), do: :ok
       end
 
+  Readability of the code is increased, as it is now clear which functions are
+  part of your API and which ones are callback implementations. To reinforce this
+  idea, `@impl true` automatically marks the function as `@doc false`, disabling
+  documentation unless `@doc` is explicitly set.
+
   ### `@compile`
 
   Defines options for module compilation. This is used to configure