Improve docs for --warnings-as-errors, closes #13443

Author: josevalim

lib/mix/lib/mix/tasks/test.ex

@@ -199,8 +199,11 @@ defmodule Mix.Tasks.Test do
       Note that in trace mode test timeouts will be ignored as timeout is set to `:infinity`
 
     * `--warnings-as-errors` *(since v1.12.0)* - treats warnings as errors and returns a non-zero
-      exit status. This option only applies to test files. To treat warnings as errors during
-      compilation and during tests, run:
+      exit status if the test suite would otherwise pass. Note that failures reported by
+      `--warnings-as-errors` cannot be retried with the `--failed` flag.
+
+      This option only applies to test files. To treat warnings as errors during compilation and
+      during tests, run:
           MIX_ENV=test mix do compile --warnings-as-errors + test --warnings-as-errors
 
   ## Configuration