Improve docs for the IEx module and some error messages as well

Author: José Valim

lib/iex/lib/iex.ex

@@ -1,19 +1,93 @@
 defrecord IEx.Config, binding: nil, cache: '', counter: 1, scope: nil, result: nil
 
 defmodule IEx do
-  @moduledoc """
-  This module implements Interactive Elixir.
+  @moduledoc %B"""
+  Welcome to IEx.
 
-  The interactive elixir needs to be set as the
-  proper `-user` when starting the Erlang VM and
-  so can be done with the help of IEx.CLI.
+  This module is the main entry point Interactive Elixir and
+  in this documentation we will talk a bit about how IEx works.
 
-  If possible, Elixir will start a tty (smart terminal)
-  which makes all control commands available in tty
-  available to the developer.
+  Notice some of the functionality described here will be available
+  depending on your terminal. In particular, if you get a message
+  saying that the smart terminal could not be run, some of the
+  features described here won't work.
+
+  ## The Break command
+
+  Inside IEx, hitting Ctrl+C will open up the BREAK menu. In this
+  menu you can quit the shell, see process and ets tables information
+  and much more.
+
+  ## The User Switch command
+
+  Besides the break command, one can type Ctrl+G to get the to
+  the user switch command. When reached, you can type `h` to
+  get more information.
+
+  In this switch, developers are able to create new shell and
+  alternate in between them. Let's give it a try:
+
+      User switch command
+       --> s 'Elixir-IEx'
+       --> c
+
+  The command above will start a new shell and connect to it.
+  Create a new variable called hello and assign some value to it:
+
+      hello = :world
+
+  Now, let's rollback to the first shell:
+
+      User switch command
+       --> c 1
+
+  Now, try to access the hello variable again:
+
+      hello
+      ** (UndefinedFunctionError) undefined function: IEx.Helpers.hello/0
+
+  The command above fails because we have changed the shells
+  and they are isolated from each other, you can access the
+  variables defined in one in the other.
+
+  The User Switch also allow developers to connect to remote
+  shells using r. Keep in mind that you can't connect to a
+  remote node if you haven't given a name to the current node
+  (i.e. Process.is_alive? must return true).
+
+  ## Expressions in IEx
+
+  As an interactive shell, IEx evalutes expressions. This has some
+  interesting consequences worthy discussing.
+
+  The first one is that the code is truly evaluated and not compiled.
+  This means that, any benchmarking done in the shell is going to have
+  skewed results. So never run any profiling nor benchmark in the shell.
+
+  Second of all, IEx alows you to break an expression into many lines,
+  since this is common in Elixir. For example:
+
+      iex(1)> "ab
+      ...(1)> c"
+      "ab\nc"
+
+  In the example above, the shell will be expecting more input until it
+  finds the closing quote. Sometimes it is not obvious which character
+  the shell is expecting, and the user may find themselves trapped in
+  the state of incomplete expression with no ability to terminate it other
+  than by exiting the shell.
+
+  For such cases, there is a special break-trigger ("#iex:break") that when
+  encountered on a line by itself will force the shell to break out of any
+  pending expression and return to its normal state:
+
+      iex(1)> ["ab
+      ...(1)> c"
+      ...(1)> "
+      ...(1)> ]
+      ...(1)> #iex:break
+      ** (TokenMissingError) iex:1: incomplete expression
 
-  In case `tty` is not available (for example, Windows),
-  a dumb terminal version is started instead.
   """
 
   @doc """

lib/iex/lib/iex/cli.ex

@@ -2,8 +2,16 @@ defmodule IEx.CLI do
   @moduledoc false
 
   @doc """
-  Starts IEx checking if tty (a termnial emulator) is available or not.
-  If so, invoke tty, otherwise go with the simple iex.
+  In order to work properly, IEx needs to be set as the
+  proper `-user` when starting the Erlang VM and we do so
+  by pointing exactly to this function.
+
+  If possible, Elixir will start a tty (smart terminal)
+  which makes all control commands available in tty
+  available to the developer.
+
+  In case `tty` is not available (for example, Windows),
+  a dumb terminal version is started instead.
   """
   def start do
     if tty_works? do
@@ -36,9 +44,15 @@ defmodule IEx.CLI do
     args =
       if remote = get_remsh(:init.get_plain_arguments) do
         unless is_alive do
-          raise ArgumentError, message: "In order to use --remsh, you need to name the current node"
+          function = fn ->
+            IO.puts(:stderr, "In order to use --remsh, you need to name the current node using --name or --sname. Aborting...")
+            System.halt(1)
+          end
+
+          { :erlang, :apply, [function, []] }
+        else
+          { remote, :erlang, :apply, [function, []] }
         end
-        { remote, :erlang, :apply, [function, []] }
       else
         { :erlang, :apply, [function, []] }
       end

lib/iex/lib/iex/helpers.ex

@@ -37,36 +37,7 @@ defmodule IEx.Helpers do
       h(Enum)
       h(Enum.reverse/1)
 
-
-  ## A note about expressions in IEx ##
-
-  IEx treats incomplete expressions in a special way, allowing one
-  to spill an expression over multiple lines. For example,
-
-      iex(1)> "ab
-      ...(1)> c"
-      "ab\nc"
-
-  In the example above, the shell will be expecting more input until it finds
-  the closing quote. Sometimes it is not obvious which character the shell is
-  expecting, and the user may find themselves trapped in the state of
-  incomplete expression with no ability to terminate it other than by exiting
-  the shell.
-
-  For such cases, there is a special break-trigger ("#iex:break") that when
-  encountered on a line by itself will force the shell to break out of any
-  pending expression and return to its normal state:
-
-      iex(1)> ["ab
-      ...(1)> c"
-      ...(1)> "
-      ...(1)> ]
-      ...(1)> #iex:break
-      ** (TokenMissingError) iex:1: incomplete expression
-          ...
-
-      iex(1)>
-
+  To learn more about IEx as a whole, just type `h(IEx)`.
   """
 
   @doc """
@@ -119,7 +90,7 @@ defmodule IEx.Helpers do
   end
 
   @doc """
-  Prints the documentation for IEx.Helpers.
+  Prints the documentation for `IEx.Helpers`.
   """
   def h() do
     IEx.Introspection.h(IEx.Helpers)