Define "nutrition facts" for "use SomeModule" (#12613)

One common concern about using Elixir libraries
is that "use SomeModule" does not make clear how
it impacts the caller. Most of the time those
changes are minor but it is impossible to know
without traversing the source code.

This pull request suggests defining a summary
alongside each module that succintly explains
the impact of using it.

This is documented as best practice in our guides
and we added the note to all of Elixir modules.

Author: josevalim

lib/elixir/lib/agent.ex

@@ -49,6 +49,12 @@ defmodule Agent do
   Thanks to the agent server process, the counter can be safely incremented
   concurrently.
 
+  > #### `use Agent` {: .info}
+  >
+  > When you `use Agent`, the `Agent` module will define a
+  > `child_spec/1` function, so your module can be used
+  > as a child in a supervision tree.
+
   Agents provide a segregation between the client and server APIs (similar to
   `GenServer`s). In particular, the functions passed as arguments to the calls to
   `Agent` functions are invoked inside the agent (the server). This distinction

lib/elixir/lib/application.ex

@@ -165,6 +165,13 @@ defmodule Application do
         end
       end
 
+  > #### `use Application` {: .info}
+  >
+  > When you `use Application`, the `Application` module will
+  > set `@behaviour Application` and define an overridable
+  > definition for the `c:stop/1` function, which is required
+  > by Erlang/OTP.
+
   The `c:start/2` callback has to spawn and link a supervisor and return `{:ok,
   pid}` or `{:ok, pid, state}`, where `pid` is the PID of the supervisor, and
   `state` is an optional application state. `args` is the second element of the

lib/elixir/lib/dynamic_supervisor.ex

@@ -123,6 +123,12 @@ defmodule DynamicSupervisor do
   `use DynamicSupervisor` will be attached to the generated `child_spec/1`
   function.
 
+  > #### `use DynamicSupervisor` {: .info}
+  >
+  > When you `use DynamicSupervisor`, the `DynamicSupervisor` module will
+  > set `@behaviour DynamicSupervisor` and define a `child_spec/1`
+  > function, so your module can be used as a child in a supervision tree.
+
   ## Name registration
 
   A supervisor is bound to the same name registration rules as a `GenServer`.

lib/elixir/lib/gen_server.ex

@@ -81,6 +81,13 @@ defmodule GenServer do
   A `cast/2` message must be handled by `c:handle_cast/2`. `GenServer`
   supports 8 callbacks, but only `c:init/1` is required.
 
+  > #### `use GenServer` {: .info}
+  >
+  > When you `use GenServer`, the `GenServer` module will
+  > set `@behaviour GenServer` and define a `child_spec/1`
+  > function, so your module can be used as a child
+  > in a supervision tree.
+
   ## Client / Server APIs
 
   Although in the example above we have used `GenServer.start_link/3` and

lib/elixir/lib/kernel.ex

@@ -5805,13 +5805,41 @@ defmodule Kernel do
 
   In such cases, developers should instead import or alias the module
   directly, so that they can customize those as they wish,
-  without the indirection behind `use/2`.
+  without the indirection behind `use/2`. Developers must also avoid
+  defining functions inside `__using__/1`.
 
-  Finally, developers should also avoid defining functions inside
-  the `__using__/1` callback, unless those functions are the default
-  implementation of a previously defined `@callback` or are functions
-  meant to be overridden (see `defoverridable/1`). Even in these cases,
-  defining functions should be seen as a "last resort".
+  Given `use MyModule` can generate any code, it may not be easy for
+  developers to understand the impact of `use MyModule`.
+
+  For this reason, to provide guidance and clarity, we recommend developers
+  to include an admonition block in their `@moduledoc` that explains how
+  `use MyModule` impacts their code. As an example, the `GenServer` documentation
+  outlines:
+
+  > #### `use GenServer` {: .info}
+  >
+  > When you `use GenServer`, the `GenServer` module will
+  > set `@behaviour GenServer` and define a `child_spec/1`
+  > function, so your module can be used as a child
+  > in a supervision tree.
+
+  This provides a quick summary of how using a module impacts the user code.
+  Keep in mind to only list changes made to the public API of the module.
+  For example, if `use MyModule` sets an internal attribute called
+  `@_my_module_info` and this attribute is never meant to be public,
+  it must not be listed.
+
+  For convenience, the markup notation to generate the admonition block
+  above is:
+
+  ```
+  > #### `use GenServer` {: .info}
+  >
+  > When you `use GenServer`, the GenServer module will
+  > set `@behaviour GenServer` and define a `child_spec/1`
+  > function, so your module can be used as a child
+  > in a supervision tree.
+  ```
   """
   defmacro use(module, opts \\ []) do
     calls =

lib/elixir/lib/supervisor.ex

@@ -397,6 +397,13 @@ defmodule Supervisor do
   `c:init/1` callback. `Supervisor.init/2` accepts the same `:strategy`,
   `:max_restarts`, and `:max_seconds` options as `start_link/2`.
 
+  > #### `use Supervisor` {: .info}
+  >
+  > When you `use Supervisor`, the `Supervisor` module will
+  > set `@behaviour Supervisor` and define a `child_spec/1`
+  > function, so your module can be used as a child
+  > in a supervision tree.
+
   `use Supervisor` also defines a `child_spec/1` function which allows
   us to run `MyApp.Supervisor` as a child of another supervisor or
   at the top of your supervision tree as:

lib/elixir/lib/task.ex

@@ -164,6 +164,12 @@ defmodule Task do
   and `Task.start_link/1` are for fire-and-forget tasks, where you don't
   care about the results or if it completes successfully or not.
 
+  > #### `use Task` {: .info}
+  >
+  > When you `use Task`, the `Task` module will define a
+  > `child_spec/1` function, so your module can be used
+  > as a child in a supervision tree.
+
   `use Task` defines a `child_spec/1` function, allowing the
   defined module to be put under a supervision tree. The generated
   `child_spec/1` can be customized with the following options:

lib/elixir/pages/library-guidelines.md

@@ -65,7 +65,7 @@ you should prefer:
 ```elixir
 case File.read("some_path_that_may_or_may_not_exist") do
   {:ok, contents} -> {:it_worked, contents}
-  {:error, _} -> :it_failed
+  {:error, _} -> :it_failed
 end
 ```
 
@@ -200,7 +200,31 @@ The code above says we are only bringing in the functions from `MyLib` so we can
 
 If the module you want to invoke a function on has a long name, such as `SomeLibrary.Namespace.MyLib`, and you find it verbose, you can leverage the `alias/2` special form and still refer to the module as `MyLib`.
 
-While there are situations where `use SomeModule` is necessary, `use` should be skipped when all it does is to `import` or `alias` other modules. In a nutshell, `alias` should be preferred, as it is simpler and clearer than `import`, while `import` is simpler and clearer than `use`.
+### Avoid undocumented `use SomeModule`
+
+In some situations, where you need to do more than importing and aliasing modules, allowing a developer to `use SomeModule` may be necessary. The benefit of `use SomeModule` is that it provides a common extension point for the Elixir ecosystem. However, given `use SomeModule` can execute any code, it may not be easy for developers to understand the impact of `use SomeModule`.
+
+For this reason, to provide guidance and clarity, we recommend library authors to include an admonition block in their `@moduledoc` that explains how `use SomeModule` impacts the developer's code. As an example, the `GenServer` documentation outlines:
+
+> #### `use GenServer` {: .info}
+>
+> When you `use GenServer`, the `GenServer` module will
+> set `@behaviour GenServer` and define a `child_spec/1`
+> function, so your module can be used as a child
+> in a supervision tree.
+
+Think of this summary as a ["Nutrition facts"](https://en.wikipedia.org/wiki/Nutrition_facts_label) for code generation. Keep in mind to only list changes made to the public API of the module. For example, if `use SomeModule` sets an internal attribute called `@_some_module_info` and this attribute is never meant to be public, it must not be listed.
+
+For convenience, the markup notation to generate the admonition block above is:
+
+```
+> #### `use GenServer` {: .info}
+>
+> When you `use GenServer`, the `GenServer` module will
+> set `@behaviour GenServer` and define a `child_spec/1`
+> function, so your module can be used as a child
+> in a supervision tree.
+```
 
 ### Avoid macros
 

lib/ex_unit/lib/ex_unit/case.ex

@@ -23,11 +23,11 @@ defmodule ExUnit.Case do
     * `:register` - when `false`, does not register this module within
       ExUnit server. This means the module won't run when ExUnit suite runs.
 
-  This module automatically includes all callbacks defined in
-  `ExUnit.Callbacks`. See that module for more information on `setup`,
-  `start_supervised`, `on_exit` and the test process life cycle.
-
-  For grouping tests together, see `describe/2` in this module.
+  > #### `use ExUnit.Case` {: .info}
+  >
+  > When you `use ExUnit.Case`, it will import the functionality
+  > from `ExUnit.Assertions`, `ExUnit.Callbacks`, `ExUnit.DocTest`,
+  > and this module itself.
 
   ## Examples
 

lib/ex_unit/lib/ex_unit/case_template.ex

@@ -20,6 +20,13 @@ defmodule ExUnit.CaseTemplate do
   ExUnit.Case` under the hood. This means you can do things like `use
   MyCase, async: true`. You can also access this options in `using/2`.
 
+  > #### `use ExUnit.CaseTemplate` {: .info}
+  >
+  > When you `use ExUnit.CaseTemplate`, it will import the functionality
+  > from `ExUnit.Assertions`, `ExUnit.Callbacks`, and this module itself.
+  > It will also define a `__using__` callback, so the module itself can
+  > be used as a template instead of `ExUnit.Case`.
+
   ## Example
 
       defmodule MyCase do