Merge pull request #2 from ysitu/refactor-flow

Implement cutoff and fix value_only use in minimum_cut
Remove asserts from docstrings.

Also some other small docstring fixes.
Return both flow_value and {flow_dict|partition} when value_only is False.
Kwargs sanity check for maximum_flow and minimum_cut.

Check that kwargs is empty if flow_func is None, if not raise NetworkXError. This way users will nor rely on the default_flow_func.
Improve interface to flow algorithms.

This commit introduces backwards incompatible changes to the interface
of flow algorithms:

1. Split maximum_flow into maximum_flow (returns a tuple flow_value, flow_dict)
and maximum_flow_value (returns only the value).

2. Split minimum_cut into minimum_cut (returns a tuple cut_value, partition)
and minimum_cut_value (returns only the value).

3. Remove the short versions max_flow and min_cut.

4. Remove flord_fulkerson_flow and ford_fulkerson_and_auxiliary

5. Remove the parameter `legacy` from ford_fulkerson. It now returns a
residual network as all other flow algorithms. I also tried to remove it
but doing so requires quite a few changes in mincost.py because the code,
tests, and the docstrings still relay on the its obsolete convention
for flow_dict.
Fix obsolete uses of maximum flow interface.
Fix obsolete uses of maximum flow interface in connectivity.

The connectivity package needs refactoring for taking advantatge of
the new conventions and algorithms of the flow package. This is only
a minimal fix.
Remove superfluous comments and small docstrings improvements.
Add example: same output that ford_fulkerson pre 1.9 with the new interface.
Document minimum cut criterion in individual maxflow functions