Merge pull request #3770 from eksperimental/summaries

Improve Summaries

13 files changed, 36 insertions, 31 deletions

diff --git a/lib/elixir/lib/bitwise.ex b/lib/elixir/lib/bitwise.ex
index 24eedaa13..a038daef3 100644
--- a/lib/elixir/lib/bitwise.ex
+++ b/lib/elixir/lib/bitwise.ex
@@ -1,8 +1,9 @@
 defmodule Bitwise do
   @moduledoc """
   This module provides macro-based operators that perform calculations
-  on (sets of) bits. In general, you should `use` the Bitwise module
-  as a whole:
+  on (sets of) bits.
+
+  In general, you should `use` the Bitwise module as a whole:
 
       iex> use Bitwise
       iex> bnot 1
diff --git a/lib/elixir/lib/enum.ex b/lib/elixir/lib/enum.ex
index a04c3e52d..d74ca931a 100644
--- a/lib/elixir/lib/enum.ex
+++ b/lib/elixir/lib/enum.ex
@@ -145,7 +145,7 @@ defmodule Enum do
 
   @moduledoc """
   Provides a set of algorithms that enumerate over collections according to the
-  `Enumerable` protocol:
+  `Enumerable` protocol.
 
       iex> Enum.map([1, 2, 3], fn(x) -> x * 2 end)
       [2, 4, 6]
diff --git a/lib/elixir/lib/exception.ex b/lib/elixir/lib/exception.ex
index 8771a69e3..56065ece4 100644
--- a/lib/elixir/lib/exception.ex
+++ b/lib/elixir/lib/exception.ex
@@ -42,7 +42,7 @@ defmodule Exception do
   def exception?(_), do: false
 
   @doc """
-  Gets the message for an exception.
+  Gets the message for an `exception`.
   """
   def message(%{__struct__: module, __exception__: true} = exception) when is_atom(module) do
     try do
@@ -95,7 +95,7 @@ defmodule Exception do
   end
 
   @doc """
-  Normalizes and formats any throw, error and exit.
+  Normalizes and formats any throw/error/exit.
 
   The message is formatted and displayed in the same
   format as used by Elixir's CLI.
@@ -128,7 +128,7 @@ defmodule Exception do
   end
 
   @doc """
-  Normalizes and formats throw/errors/exits and stacktrace.
+  Normalizes and formats throw/errors/exits and stacktraces.
 
   It relies on `format_banner/3` and `format_stacktrace/1`
   to generate the final format.
@@ -155,7 +155,7 @@ defmodule Exception do
   end
 
   @doc """
-  Formats an exit, returns a string.
+  Formats an exit. It returns a string.
 
   Often there are errors/exceptions inside exits. Exits are often
   wrapped by the caller and provide stacktraces too. This function
@@ -447,7 +447,7 @@ defmodule Exception do
   end
 
   @doc """
-  Formats the given file and line as shown in stacktraces.
+  Formats the given `file` and `line` as shown in stacktraces.
   If any of the values are `nil`, they are omitted.
 
   ## Examples
diff --git a/lib/elixir/lib/kernel.ex b/lib/elixir/lib/kernel.ex
index 34ad475d1..7ed359af6 100644
--- a/lib/elixir/lib/kernel.ex
+++ b/lib/elixir/lib/kernel.ex
@@ -7,11 +7,12 @@ import :elixir_bootstrap
 
 defmodule Kernel do
   @moduledoc """
-  `Kernel` provides the default macros and functions
-  Elixir imports into your environment. These macros and functions
-  can be skipped or cherry-picked via the `import` macro. For
-  instance, if you want to tell Elixir not to import the `if`
-  macro, you can do:
+  Provides the default macros and functions Elixir imports into your
+  environment.
+
+  These macros and functions can be skipped or cherry- picked via the
+  `import` macro. For instance, if you want to tell Elixir not to
+  import the `if` macro, you can do:
 
       import Kernel, except: [if: 2]
 
diff --git a/lib/elixir/lib/kernel/special_forms.ex b/lib/elixir/lib/kernel/special_forms.ex
index f2c0dc7d9..170b8bc24 100644
--- a/lib/elixir/lib/kernel/special_forms.ex
+++ b/lib/elixir/lib/kernel/special_forms.ex
@@ -1,12 +1,11 @@
 defmodule Kernel.SpecialForms do
   @moduledoc """
-  In this module we define Elixir special forms. Special forms
-  cannot be overridden by the developer and are the basic
-  building blocks of Elixir code.
+  Special forms are the basic building blocks of Elixir, and therefore
+  they cannot be overridden by the developer.
 
-  Some of those forms are lexical (like `alias`, `case`, etc).
-  The macros `{}` and `<<>>` are also special forms used to define
-  tuple and binary data structures respectively.
+  We define them in this module. Some of these forms are lexical (like
+  `alias`, `case`, etc). The macros `{}` and `<<>>` are also special
+  forms used to define tuple and binary data structures respectively.
 
   This module also documents Elixir's pseudo variables (`__ENV__`,
   `__MODULE__`, `__DIR__` and `__CALLER__`). Pseudo variables return
diff --git a/lib/elixir/lib/keyword.ex b/lib/elixir/lib/keyword.ex
index 7235e3160..94f167219 100644
--- a/lib/elixir/lib/keyword.ex
+++ b/lib/elixir/lib/keyword.ex
@@ -1,5 +1,7 @@
 defmodule Keyword do
   @moduledoc """
+  A set of functions for working with keywords.
+
   A keyword is a list of tuples where the first element
   of the tuple is an atom and the second element can be
   any value.
diff --git a/lib/elixir/lib/list.ex b/lib/elixir/lib/list.ex
index 16f916dc4..580f152f8 100644
--- a/lib/elixir/lib/list.ex
+++ b/lib/elixir/lib/list.ex
@@ -1,8 +1,8 @@
 defmodule List do
   @moduledoc """
-  Implements functions that only make sense for lists
-  and cannot be part of the Enum protocol. In general,
-  favor using the Enum API instead of List.
+  Specialized functions that works only on lists.
+
+  In general, favor using the `Enum` API instead of `List`.
 
   Some functions in this module expect an index. Index
   access for list is linear. Negative indexes are also
diff --git a/lib/elixir/lib/map.ex b/lib/elixir/lib/map.ex
index 675babfd9..03191cafe 100644
--- a/lib/elixir/lib/map.ex
+++ b/lib/elixir/lib/map.ex
@@ -1,6 +1,6 @@
 defmodule Map do
   @moduledoc """
-  A Dict implementation that works on maps.
+  A `Dict` implementation that works on maps.
 
   Maps are key-value stores where keys are compared using
   the match operator (`===`). Maps can be created with
diff --git a/lib/elixir/lib/module.ex b/lib/elixir/lib/module.ex
index 5a04027ad..a2ff18fee 100644
--- a/lib/elixir/lib/module.ex
+++ b/lib/elixir/lib/module.ex
@@ -1,8 +1,9 @@
 defmodule Module do
   @moduledoc ~S'''
-  This module provides many functions to deal with modules during
-  compilation time. It allows a developer to dynamically attach
-  documentation, add, delete and register attributes and so forth.
+  Provides functions to deal with modules during compilation time.
+
+  It allows a developer to dynamically add, delete and register
+  attributes, attach documentation and so forth.
 
   After a module is compiled, using many of the functions in
   this module will raise errors, since it is out of their scope
diff --git a/lib/elixir/lib/range.ex b/lib/elixir/lib/range.ex
index 7411205b6..0f34001aa 100644
--- a/lib/elixir/lib/range.ex
+++ b/lib/elixir/lib/range.ex
@@ -1,8 +1,8 @@
 defmodule Range do
   @moduledoc """
-  Defines a Range.
+  Defines a range.
 
-  A Range represents a discrete number of values where
+  A range represents a discrete number of values where
   the first and last values are integers.
 
   Ranges can be either increasing (first <= last) or
diff --git a/lib/elixir/lib/record.ex b/lib/elixir/lib/record.ex
index 8d3c3ab25..80a3d9780 100644
--- a/lib/elixir/lib/record.ex
+++ b/lib/elixir/lib/record.ex
@@ -1,6 +1,6 @@
 defmodule Record do
   @moduledoc """
-  Module to work, define and import records.
+  Module to work with, define and import records.
 
   Records are simply tuples where the first element is an atom:
 
diff --git a/lib/elixir/lib/regex.ex b/lib/elixir/lib/regex.ex
index 8e9000593..184c824e2 100644
--- a/lib/elixir/lib/regex.ex
+++ b/lib/elixir/lib/regex.ex
@@ -1,6 +1,7 @@
 defmodule Regex do
   @moduledoc ~S"""
-  Regular expressions for Elixir built on top of Erlang's `:re` module.
+  Provides regular expressions for Elixir. Built on top of Erlang's `:re`
+  module.
 
   As the `:re` module, Regex is based on PCRE
   (Perl Compatible Regular Expressions). More information can be
diff --git a/lib/mix/lib/mix/scm.ex b/lib/mix/lib/mix/scm.ex
index 6b57e0ecb..796d02ff5 100644
--- a/lib/mix/lib/mix/scm.ex
+++ b/lib/mix/lib/mix/scm.ex
@@ -1,7 +1,7 @@
 defmodule Mix.SCM do
   @moduledoc """
   This module provides helper functions and defines the
-  behaviour required by any SCM used by mix.
+  behaviour required by any SCM used by Mix.
   """
 
   @type opts :: Keyword.t