       end
 
   However, do not provide `__using__/1` if all it does is to import,
-  alias or require the module itself. For example, do not:
+  alias or require the module itself. For example, avoid this:
 
       defmodule MyModule do
-        defmacro __using__(opts) do
+        defmacro __using__(_opts) do
           quote do
             import MyModule
           end
         end
       end
 
-  In such cases, developers must just import or alias the module
-  directly, allowing developers to customize those as they wish,
+  In such cases, developers should just import or alias the module
+  directly, so that they can customize those as they wish,
   without the indirection behind `use/2`.
 
   Finally, developers should also avoid defining functions inside
   the `__using__/1` callback, unless those functions are the default
-  implementation of a previously defined `@callback`. In case you
-  want to provide some existing functionality to the user module,
-  please define it in a module which will be imported accordingly.
+  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 resource".
+
+  In case you want to provide some existing functionality to the user module,
+  please define it in a module which will be imported accordingly; for example,
+  `ExUnit.Case` doesn't define the `test/2` macro in the module that calls
+  `use ExUnit.Case`, but it defines `ExUnit.Case.test/2` and just imports that
+  into the caller when used.
   """
   defmacro use(module, opts \\ []) do
     calls = Enum.map(expand_aliases(module, __CALLER__), fn

        end
      end

  Where `__using__/1` is just a regular macro that can be defined
  in any module:

      defmodule MyModule do
        defmacro __using__(opts) do
          quote do
            # code that will run in the module that uses MyModule
          end
        end
      end

  ## Best practices

  `__using__/1` is typically used when there is a need to set some state
  (via module attributes) or callbacks (like `@before_compile`)
  into the caller.

  `__using__/1` may also be used to alias, require or import functionality
  from different modules:

      defmodule MyModule do

        end
      end

  In this example, `ExUnit.Case.__using__/1` is called with the keyword list
  `[async: true]` as its argument; `use/2` translates to:

      defmodule AssertionTest do
        require ExUnit.Case
