Improves docs for tasks and shell (#9735)

3 files changed, 67 insertions, 8 deletions

diff --git a/lib/mix/lib/mix.ex b/lib/mix/lib/mix.ex
index 04e5e466a..c6c0498ad 100644
--- a/lib/mix/lib/mix.ex
+++ b/lib/mix/lib/mix.ex
@@ -351,6 +351,16 @@ defmodule Mix do
   performing IO (see `Mix.Shell.Process`).
 
   By default, this returns `Mix.Shell.IO`.
+
+  This function is often to call functions in the current shell:
+
+
+      Mix.shell().info("Preparing to do something dangerous...")
+
+      if Mix.shell().yes?("Are you sure?") do
+        # do something dangerous
+      end
+
   """
   @spec shell() :: module
   def shell do
@@ -358,10 +368,26 @@ defmodule Mix do
   end
 
   @doc """
-  Sets the current shell.
+  Sets the current shell. As an argument you may pass `Mix.Shell.IO`,
+  `Mix.Shell.Process`, `Mix.Shell.Quiet`, or any module that implements
+  the `Mix.Shell` behaviour.
+
+  ## Examples
+
+      iex> Mix.shell(Mix.Shell.IO)
+      :ok
 
   After calling this function, `shell` becomes the shell that is returned by
   `shell/0`.
+
+  You can use `shell/0` and `shell/1` to temporarily switch shells, for example,
+  if you want to run a Mix Task that normally produces a lot of output:
+
+      shell = Mix.shell()
+      Mix.shell(Mix.Shell.Quiet)
+      Mix.Task.run("noisy.task")
+      Mix.shell(shell)
+
   """
   @spec shell(module) :: :ok
   def shell(shell) do
diff --git a/lib/mix/lib/mix/shell/io.ex b/lib/mix/lib/mix/shell/io.ex
index 252148db3..fe1462c7e 100644
--- a/lib/mix/lib/mix/shell/io.ex
+++ b/lib/mix/lib/mix/shell/io.ex
@@ -50,6 +50,13 @@ defmodule Mix.Shell.IO do
 
   The user must press Enter or type one of "y", "yes", "Y", "YES" or
   "Yes".
+
+  For example:
+  ```
+  if Mix.shell().yes?("Are you sure?") do
+    # do something...
+  end
+  ```
   """
   def yes?(message) do
     print_app()
diff --git a/lib/mix/lib/mix/task.ex b/lib/mix/lib/mix/task.ex
index 8e1f8994f..b1cfe2ba6 100644
--- a/lib/mix/lib/mix/task.ex
+++ b/lib/mix/lib/mix/task.ex
@@ -1,23 +1,49 @@
 defmodule Mix.Task do
   @moduledoc """
-  A simple module that provides conveniences for creating,
-  loading and manipulating tasks.
+  A module that provides conveniences for creating,
+  loading, and manipulating tasks.
 
-  A Mix task can be defined by simply using `Mix.Task`
-  in a module starting with `Mix.Tasks.` and defining
-  the `run/1` function:
+  A Mix task can be defined by using `Mix.Task`
+  in a module whose name starts with `Mix.Tasks.` and which defines
+  the `run/1` function. Typically, task modules live inside the
+  `lib/mix/tasks/` directory, and their file names use dot separators
+  instead of underscores (e.g. `deps.clean.ex`).
 
       defmodule Mix.Tasks.Echo do
+        @moduledoc "Printed when the user requests `mix help echo`"
+
         use Mix.Task
 
+        @shortdoc "Echoes arguments"
+
         @impl Mix.Task
         def run(args) do
           Mix.shell().info(Enum.join(args, " "))
         end
       end
 
-  The `run/1` function will receive a list of all arguments passed
-  to the command line.
+  The `run/1` function will receive a list of all command line
+  arguments passed, parsed via `OptionParser.split/1` (which
+  groups arguments by single or double quotes).
+
+  For example, if the `args` in the above `echo` task were
+  inspected, you might see something like this:
+
+      mix echo 'A and B' C --test
+      ["A and B", "C", "--test"]
+
+  Define the `@shortdoc` attribute if you wish to make the task
+  publicly visible on `mix help`. Omit this attribute if you do
+  not want your task to be listed on `mix help`.
+
+  After creating a task module, run `mix compile` and any public
+  tasks should become visible to `mix help`.
+
+  The command name will correspond to the portion of the module
+  name following `Mix.Tasks.`. For example, a module name of
+  `Mix.Tasks.Deps.Clean` corresponds to a task name of
+  `deps.clean`.
+
 
   ## Attributes