Merge pull request #491 from zzhengnan/update-docs

Update official docs

Author: eriknw

doc/source/control.rst

@@ -38,28 +38,27 @@ Programming is hard when we have to juggle many code elements of each type at
 the same time.  Good programming is about managing these three elements so that
 the developer is only required to think about a handful of them at a time.  For
 example we might collect many integer variables into a list of integers or
-build a big function out of smaller ones.  While we have natural ways to manage
-data and functions, control flow presents more of a challenge.
+build a big function out of smaller ones.
 
 We organize our data into **data structures** like lists, dictionaries, or objects
 in order to group related data together -- this allows us to manipulate large
 collections of related data as if we were only manipulating a single entity.
 
-We **build large functions out of smaller ones**; enabling us to break up a
+We **build large functions out of smaller ones**, enabling us to break up a
 complex task like doing laundry into a sequence of simpler tasks.
 
 .. code::
 
     def do_laundry(clothes):
-        wet_clothes = wash(clothes, coins)
-        dry_clothes = dry(wet_clothes, coins)
+        wet_clothes = wash(clothes)
+        dry_clothes = dry(wet_clothes)
         return fold(dry_clothes)
 
-**Control flow is more challenging**; how do we break down complex control flow
-into simpler pieces that fit in our brain?  How do we encapsulate commonly
-recurring patterns?
+While we have natural ways to manage data and functions, **control flow presents more of a challenge**.
+How do we break down complex control flow into simpler pieces that fit in our brain?
+How do we encapsulate commonly recurring patterns?
 
-Lets motivate this with an example of a common control structure, applying a
+Let's motivate this with an example of a common control structure, applying a
 function to each element in a list.  Imagine we want to download the HTML
 source for a number of webpages.
 
@@ -71,7 +70,6 @@ source for a number of webpages.
     html_texts = []
     for item in urls:
         html_texts.append(urlopen(item))
-    return html_texts
 
 Or maybe we want to compute the Fibonacci numbers on a particular set of
 integers
@@ -82,7 +80,6 @@ integers
     fib_integers = []
     for item in integers:
         fib_integers.append(fib(item))
-    return fib_integers
 
 These two unrelated applications share an identical control flow pattern.  They
 apply a function (``urlopen`` or ``fib``) onto each element of an input list
@@ -156,8 +153,8 @@ Most programmers however don't know about the many cousins of
     >>> groupby(len, names)
     {3: ['Bob', 'Dan'], 5: ['Alice', 'Edith', 'Frank'], 7: ['Charlie']}
 
-Groupby collects each element of a list into sublists determined by the value
-of a function.  Lets see ``groupby`` in action again, grouping numbers by
+``groupby`` collects each element of a list into sublists determined by the value
+of a function.  Let's see ``groupby`` in action again, grouping numbers by
 evenness.
 
 .. code::
@@ -186,6 +183,9 @@ like they may have repeated the ``map`` control pattern.  When we identify code
 as a ``groupby`` operation we mentally collapse the detailed manipulation into
 a single concept.
 
+Additional Considerations
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
 The Toolz library contains dozens of patterns like ``map`` and ``groupby``.
 Learning a core set (maybe a dozen) covers the vast majority of common
 programming tasks often done by hand.

doc/source/curry.rst

@@ -8,7 +8,7 @@ higher order function from ``functools``.  Currying provides syntactic sugar.
 .. code::
 
     >>> double = partial(mul, 2)    # Partial evaluation
-    >>> doubled = double(2)         # Currying
+    >>> doubled = double(5)         # Currying
 
 This syntactic sugar is valuable when developers chain several higher order
 functions together.
@@ -54,7 +54,7 @@ In general
     >>> def g(z):
     ...     return f(a, b, z)
 
-    >>> # partially evaluate f with known values a and b
+    >>> # alternatively we could use `partial`
     >>> g = partial(f, a, b)
 
 Curry
@@ -74,7 +74,7 @@ compute a result.
 
     >>> double = mul(2)     # mul didn't receive enough arguments to evaluate
     ...                     # so it holds onto the 2 and waits, returning a
-    ...                     # partially evaluated function, double
+    ...                     # partially evaluated function `double`
 
     >>> double(5)
     10

doc/source/laziness.rst

@@ -36,7 +36,7 @@ Computation
 -----------
 
 We can lazily operate on lazy iterators without doing any actual computation.
-For example lets read the book in upper case
+For example let's read the book in upper case
 
 .. code::
 

doc/source/parallelism.rst

@@ -74,8 +74,8 @@ multiprocessing, to distributed computation all with the same domain code.
 This smooth transition is possible because
 
 1.  The ``map`` abstraction is a simple function call and so can be replaced.
-    This transformation would be difficult if we had written our code with a
-    for loop or list comprehension
+    By contrast, this transformation would be difficult if we had written our code with a
+    for loop or list comprehension.
 2.  The operation ``wordcount`` is separate from the parallel solution.
 3.  The task is embarrassingly parallel, needing only a very simple parallel
     strategy.  Fortunately this is the common case.
@@ -90,5 +90,5 @@ general solution is to build algorithms that operate around a user-supplied
 parallel map function.
 
 In particular we provide a parallel ``fold`` in ``toolz.sandbox.parallel.fold``.
-This fold can work equally well with ``multiprocessing.Pool.map``
-``threading.Pool.map`` or ``ipyparallel``'s ``map_async``.
+This fold can work equally well with ``multiprocessing.Pool.map``,
+``threading.Pool.map``, or ``ipyparallel``'s ``map_async``.

doc/source/streaming-analytics.rst

@@ -38,7 +38,7 @@ These functions correspond to the SQL commands ``SELECT`` and ``WHERE``.
    ...                map(get([1, 2])),
    ...                list)
 
-Note: this uses the `curried`_ versions of ``map`` and ``filter``.
+Note: this uses the `curried`` versions of ``map`` and ``filter``.
 
 Of course, these operations are also well supported with standard
 list/generator comprehension syntax.  This syntax is more often used and
@@ -89,7 +89,7 @@ groups.
     'M': [(2, 'Bob', 200, 'M'), (3, 'Charlie', 150, 'M'), (4, 'Dennis', 50, 'M')]}
 
    >>> valmap(compose(sum, pluck(2)),
-   ...        _)
+   ...        _)  # The underscore captures results from the previous prompt
    {'F': 400, 'M': 400}
 
 
@@ -116,8 +116,8 @@ understand this section you should first be familiar with the builtin function
 
 The ``reduceby`` operation takes a key function, like ``get(3)`` or ``lambda x:
 x[3]``, and a binary operator like ``add`` or ``lesser = lambda acc, x: acc if
-acc < x else x``.  It successively applies the key function to each item in
-succession, accumulating running totals for each key by combining each new
+acc < x else x``.  It applies the key function to each item in succession,
+accumulating running totals for each key by combining each new
 value with the previous using the binary operator.  It can't accept full
 reduction operations like ``sum`` or ``min`` as these require access to the
 entire group at once.  Here is a simple example:
@@ -180,8 +180,9 @@ common first column, id.
 .. code::
 
    SELECT accounts.name, addresses.address
-   FROM accounts, addresses
-   WHERE accounts.id = addresses.id;
+   FROM accounts
+   JOIN addresses
+   ON accounts.id = addresses.id;
 
 
 .. code::

doc/source/tips-and-tricks.rst

@@ -2,7 +2,7 @@ Tips and Tricks
 ===============
 
 Toolz functions can be combined to make functions that, while common, aren't
-a part of toolz's standard library. This section presents
+a part of toolz's standard offerings. This section presents
 a few of these recipes.