Merge pull request #1385 from jwarwick/inspect_docs

Fixed doc typos for Inspect

Author: José Valim

lib/elixir/lib/inspect.ex

@@ -13,13 +13,13 @@ defprotocol Inspect do
   followed by the inspecting options, represented by the record
   `Inspect.Opts`.
 
-  Inspection is done by using the functions available in
+  Inspection is done using the functions available in
   `Inspect.Algebra` and by calling `Kernel.inspect/2` recursively
-  passing the `Inspect.Opts` as argument. When `Kernel.inspect/2`
-  receives a `Inspect.Opts` record as second argument, it returns
+  passing the `Inspect.Opts` as an argument. When `Kernel.inspect/2`
+  receives an `Inspect.Opts` record as the second argument, it returns
   the underlying algebra document instead of the formatted string.
 
-  Many times, inspecting a structure can be implemented in function
+  Many times, inspecting a structure can be implemented using functions
   of the existing entities. For example, here is `HashSet`'s `inspect`
   implementation:
 
@@ -33,13 +33,13 @@ defprotocol Inspect do
 
   The `concat` function comes from `Inspect.Algebra` and it
   concatenates algebra documents together. In the example above,
-  it is concatenating the string `"HashSet<"` (all strings are a
-  valid algebra document that keeps their formatting when pretty
+  it is concatenating the string `"HashSet<"` (all strings are 
+  valid algebra documents that keep their formatting when pretty
   printed), the document returned by `Kernel.inspect/2` and the
   other string `">"`.
 
-  Since regular strings are a valid entity in an algebra document,
-  an implementation of inspect may as well simply return a binary,
+  Since regular strings are valid entities in an algebra document,
+  an implementation of inspect may simply return a binary,
   although that will devoid it of any pretty-printing.
   """
 
@@ -50,8 +50,8 @@ defimpl Inspect, for: Atom do
   require Macro
 
   @doc """
-  Represents the atom as an Elixir term. The atoms false, true
-  and nil are simply quoted. Modules are properly represented
+  Represents the atom as an Elixir term. The atoms `false`, `true`
+  and `nil` are simply quoted. Modules are properly represented
   as modules using the dot notation.
 
   Notice that in Elixir, all operators can be represented using
@@ -193,7 +193,7 @@ end
 
 defimpl Inspect, for: List do
   @doc %B"""
-  Represents a list checking if it can be printed or not.
+  Represents a list, checking if it can be printed or not.
   If so, a single-quoted representation is returned,
   otherwise the brackets syntax is used. Keywords are
   printed in keywords syntax.
@@ -249,7 +249,7 @@ end
 
 defimpl Inspect, for: Tuple do
   @doc """
-  Inspect tuples. If the tuple represents a record,
+  Represents tuples. If the tuple represents a record,
   it shows it nicely formatted using the access syntax.
 
   ## Examples
@@ -316,10 +316,10 @@ defimpl Inspect, for: Number do
   @doc """
   Represents the number as a string.
 
-  Floats are represented using the shorted, correctly rounded string
+  Floats are represented using the shortened, correctly rounded string
   that converts to float when read back with `binary_to_float/1`. This
-  is done via the Erlang implementation of the "Printing Floating-Point
-  Numbers Quickly and Accurately" in Proceedings of the SIGPLAN '96
+  is done via the Erlang implementation of _Printing Floating-Point
+  Numbers Quickly and Accurately_ in Proceedings of the SIGPLAN '96
   Conference on Programming Language Design and Implementation.
 
   ## Examples
@@ -338,7 +338,7 @@ defimpl Inspect, for: Number do
 end
 
 defimpl Inspect, for: Regex do
-  @moduledoc %B"""
+  @doc %B"""
   Represents the Regex using the `%r""` syntax.
 
   ## Examples

lib/elixir/lib/inspect/algebra.ex

@@ -18,10 +18,10 @@ defmodule Inspect.Algebra do
       iex> Inspect.Algebra.pretty(doc, 80)
       "foo"
 
-  The functions `nest/2`, `space/2` and `line/2` helps you put the
+  The functions `nest/2`, `space/2` and `line/2` help you put the
   document together into a rigid structure. However, the document
   algebra gets interesting when using functions like `break/2`, which
-  converts the given string into a line break depending on much space
+  converts the given string into a line break depending on how much space
   there is to print. Let's glue two docs together with a break and then
   render it:
 
@@ -30,28 +30,28 @@ defmodule Inspect.Algebra do
       "a b"
 
   Notice the break was represented as is, because we haven't reached
-  a line limit. Once we do, it is replaced by a new line:
+  a line limit. Once we do, it is replaced by a newline:
 
       iex> doc = Inspect.Algebra.glue(String.duplicate("a", 20), " ", "b")
       iex> Inspect.Algebra.pretty(doc, 10)
       "aaaaaaaaaaaaaaaaaaaa\nb"
 
   Finally, this module also contains Elixir related functions, a bit
-  tied up to Elixir formatting, namely `surround/3` and `surround_many/5`.
+  tied to Elixir formatting, namely `surround/3` and `surround_many/5`.
 
   ## Implementation details
 
   The original Haskell implementation of the algorithm by [Wadler][1]
   relies on lazy evaluation to unfold document groups on two alternatives:
-  `:flat` (breaks as spaces) and `:broken` (breakes as newlines).
-  Implementing the same logic on a strict language such as Elixir leads
-  to an exponential growth of the possible documents, unless document
+  `:flat` (breaks as spaces) and `:broken` (breaks as newlines).
+  Implementing the same logic in a strict language such as Elixir leads
+  to an exponential growth of possible documents, unless document
   groups are encoded explictly as `:flat` or `:broken`. Those groups are
   then reduced to a simple document, where the layout is already decided,
   per [Lindig][0].
 
   Custom pretty printers can be implemented using the documents returned
-  by this module and by providing its own rendenring functions.
+  by this module and by providing their own rendering functions.
 
     [0]: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.34.2200
     [1]: http://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf
@@ -76,7 +76,7 @@ defmodule Inspect.Algebra do
   defrecordp :doc_group, :doc_group, [doc: :doc_nil]
 
   @doc """
-  Returns :doc_nil which is a document entity used to represent
+  Returns `:doc_nil` which is a document entity used to represent
   nothingness. Takes no arguments.
 
   ## Examples
@@ -109,7 +109,7 @@ defmodule Inspect.Algebra do
   def concat(docs), do: folddoc(docs, concat(&1, &2))
 
   @doc """
-  Nests document entity x positions deep. Nesting will be
+  Nests document entity `x` positions deep. Nesting will be
   appended to the line breaks.
 
   ## Examples
@@ -132,12 +132,12 @@ defmodule Inspect.Algebra do
 
   Let's glue two docs together with a break and then render it:
 
-    iex> doc = Inspect.Algebra.glue("a", " ", "b")
-    iex> Inspect.Algebra.pretty(doc, 80)
-    "a b"
+      iex> doc = Inspect.Algebra.glue("a", " ", "b")
+      iex> Inspect.Algebra.pretty(doc, 80)
+      "a b"
 
   Notice the break was represented as is, because we haven't reached
-  a line limit. Once we do, it is replaced by a new line:
+  a line limit. Once we do, it is replaced by a newline:
 
       iex> doc = Inspect.Algebra.glue(String.duplicate("a", 20), " ", "b")
       iex> Inspect.Algebra.pretty(doc, 10)
@@ -157,8 +157,8 @@ defmodule Inspect.Algebra do
   def glue(x, y), do: concat(x, concat(break, y))
 
   @doc """
-  Inserts a break, passed as second argument, between two docs,
-  the first and the third argument.
+  Inserts a break, passed as the second argument, between two docs,
+  the first and the third arguments.
   """
   @spec glue(doc, binary, doc) :: :doc_cons_t
   def glue(x, g, y) when is_binary(g), do: concat(x, concat(break(g), y))
@@ -243,7 +243,7 @@ defmodule Inspect.Algebra do
   @doc %B"""
   Surrounds a document with characters.
 
-  Puts the document between left and right enclosing and nests it.
+  Puts the document between left and right enclosing and nesting it.
   The document is marked as a group, to show the maximum as possible
   concisely together.
 
@@ -261,8 +261,8 @@ defmodule Inspect.Algebra do
 
   @doc %B"""
   Maps and glues a collection of items together using the given separator
-  and surround them. A limit can be passed which, once reached, stops
-  glueing and outputs "..." instead.
+  and surrounds them. A limit can be passed which, once reached, stops
+  gluing and outputs "..." instead.
 
   ## Examples
 
@@ -335,7 +335,7 @@ defmodule Inspect.Algebra do
 
   @doc """
   The pretty printing function.
-  Takes maximum width and a document to print as its arguments and returns the string
+  Takes the maximum width and a document to print as its arguments and returns the string
   representation of the best layout for the document to fit in the given width.
   """
   @spec pretty(doc, non_neg_integer) :: binary