DOC: Address reviewer comments

Author: HaoZeke

doc/source/f2py/distutils.rst

@@ -4,7 +4,7 @@ Using via `numpy.distutils`
 
 .. currentmodule:: numpy.distutils.core
 
-:mod:`numpy.distutils` is part of NumPy; and extends the standard Python
+:mod:`numpy.distutils` is part of NumPy, and extends the standard Python
 ``distutils`` module to deal with Fortran sources and F2PY signature files, e.g.
 compile Fortran sources, call F2PY to construct extension modules, etc.
 
@@ -34,7 +34,7 @@ Extensions to ``distutils``
 
 * :class:`Extension` class argument ``sources`` may contain Fortran source
   files. In addition, the list ``sources`` may contain at most one
-  F2PY signature file; in this case, the name of an Extension module must
+  F2PY signature file, and in this case, the name of an Extension module must
   match with the ``<modulename>`` used in signature file. It is
   assumed that an F2PY signature file contains exactly one ``python
   module`` block.
@@ -52,7 +52,7 @@ Extensions to ``distutils``
   ``config_fc``
     to change Fortran compiler options.
 
-  as well as ``build_ext`` and  ``build_clib`` commands which are also enhanced
+  Additionally, the ``build_ext`` and ``build_clib`` commands are also enhanced
   to support Fortran sources.
 
   Run

doc/source/f2py/f2py.getting-started.rst

@@ -28,9 +28,9 @@ Depending on the situation, these steps can be carried out in a single composite
 command or step-by-step; in which case some steps can be omitted or combined
 with others.
 
-Below we describe three typical approaches of using F2PY. These can be read in
+Below, we describe three typical approaches of using F2PY. These can be read in
 order of increasing effort, but also cater to different access levels depending
-on whether the Fortran code can be modified freely.
+on whether the Fortran code can be freely modified.
 
 The following example Fortran 77 code will be used for
 illustration, save it as ``fib1.f``:
@@ -42,17 +42,17 @@ illustration, save it as ``fib1.f``:
 The quick way
 ==============
 
-The quickest way to expose the Fortran subroutine ``FIB`` to Python is
-to run
+The quickest way to wrap the Fortran subroutine ``FIB`` for use in Python is to
+run
 
 ::
 
   python -m numpy.f2py -c fib1.f -m fib1
 
-This command builds (see the ``-c`` flag, or execute ``python -m numpy.f2py``
-without arguments to see the explanation of command line options) an extension
-module ``fib1.so`` (see the ``-m`` flag) to the current directory. Now, in Python
-the Fortran subroutine ``FIB`` is accessible via ``fib1.fib``::
+This command compiles and wraps ``fib1.f`` (``-c``) to create the extension
+module ``fib1.so`` (``-m``) in the current directory. A list of command line
+options can be seen by executing ``python -m numpy.f2py``.  Now, in Python the
+Fortran subroutine ``FIB`` is accessible via ``fib1.fib``::
 
   >>> import numpy as np
   >>> import fib1
@@ -116,9 +116,8 @@ the Fortran subroutine ``FIB`` is accessible via ``fib1.fib``::
       >>> print(a)
       [1 1 1 1 1 1 1 1]
 
-    Clearly, this is not an expected behaviour; especially since Fortran
-    typically passes by reference. The fact that the above example worked with
-    ``dtype=float`` is considered accidental.
+    Clearly, this is unexpected, as Fortran typically passes by reference. That
+    the above example worked with ``dtype=float`` is considered accidental.
 
     F2PY provides an ``intent(inplace)`` attribute that modifies
     the attributes of an input array so that any changes made by
@@ -131,30 +130,30 @@ the Fortran subroutine ``FIB`` is accessible via ``fib1.fib``::
       >>> print(a)
       [  0.   1.   1.   2.   3.   5.   8.  13.]
 
-    However, the recommended way to get changes made by Fortran subroutine
-    propagate to Python is to use ``intent(out)`` attribute. This approach is
+    However, the recommended way to have changes made by Fortran subroutine
+    propagate to Python is to use the ``intent(out)`` attribute. That approach is
     more efficient and also cleaner.
 
   * The usage of ``fib1.fib`` in Python is very similar to using ``FIB`` in
-    Fortran. However, using *in situ* output arguments in Python indicates a
-    poor style as there are no safety mechanisms in Python to protect against
-    wrong argument types. When using Fortran or C, compilers naturally discover
-    any type mismatches during the compilation process, but in Python the types
-    must be checked at runtime. So, using *in situ* output arguments in Python
-    may give rise to difficult to find bugs, not to mention the fact that the
+    Fortran. However, using *in situ* output arguments in Python is poor style,
+    as there are no safety mechanisms in Python to protect against wrong
+    argument types. When using Fortran or C, compilers discover any type
+    mismatches during the compilation process, but in Python the types must be
+    checked at runtime. Consequently, using *in situ* output arguments in Python
+    may lead to difficult to find bugs, not to mention the fact that the
     codes will be less readable when all required type checks are implemented.
 
-  Though the approach to exposing Fortran routines to Python discussed so far is
+  Though the approach to wrapping Fortran routines for Python discussed so far is
   very straightforward, it has several drawbacks (see the comments above).
-  These drawbacks are due to the fact that there is no way for F2PY to determine
+  The drawbacks are due to the fact that there is no way for F2PY to determine
   the actual intention of the arguments; that is there is ambiguity in
-  distinguishing between input, output arguments. So, F2PY conservatively
-  assumes that all arguments are input arguments by default.
+  distinguishing between input and output arguments. Consequently, F2PY assumes
+  that all arguments are input arguments by default.
 
-  However, there are ways (see below) how to remove this ambiguity; essentially
-  by "teaching" F2PY about the true intentions (among other things) of function
-  arguments; subsequently F2PY is then able to generate more Pythonic (more
-  explicit, easier to use, and less error prone) wrappers to Fortran functions.
+  However, there are ways (see below) to remove this ambiguity by "teaching"
+  F2PY about the true intentions of function arguments, and F2PY is then able to
+  generate more explicit, easier to use, and less error prone wrappers for
+  Fortran functions.
 
 The smart way
 ==============
@@ -175,13 +174,13 @@ one.
      :language: fortran
 
 * Next, we'll teach F2PY that the argument ``n`` is an input argument (using the
-  ``intent(in)`` attribute) and that the result, i.e. the contents of ``a``
-  after calling Fortran function ``FIB``, should be returned to Python (using
+  ``intent(in)`` attribute) and that the result, i.e., the contents of ``a``
+  after calling the Fortran function ``FIB``, should be returned to Python (using
   the ``intent(out)`` attribute). In addition, an array ``a`` should be created
   dynamically using the size determined by the input argument ``n`` (using the
   ``depend(n)`` attribute to indicate this dependence relation).
 
-  The content of a suitably modified version of ``fib1.pyf`` (saved as
+  The contents of a suitably modified version of ``fib1.pyf`` (saved as
   ``fib2.pyf``) is as follows:
 
   .. literalinclude:: ./code/fib2.pyf
@@ -214,13 +213,12 @@ In Python::
 
 .. note::
 
-  * Clearly, the signature of ``fib2.fib`` now more closely corresponds to the
+  * The signature of ``fib2.fib`` now more closely corresponds to the
     intention of Fortran subroutine ``FIB``: given the number ``n``,
     ``fib2.fib`` returns the first ``n`` Fibonacci numbers as a NumPy array.
-    Also, the new Python signature ``fib2.fib`` rules out the surprises that we
-    experienced with ``fib1.fib``.
+    The new Python signature ``fib2.fib`` also rules out the unexpected behaviour in ``fib1.fib``.
 
-  * Note that by default using a single ``intent(out)`` also implies
+  * Note that by default, using a single ``intent(out)`` also implies
     ``intent(hide)``. Arguments that have the ``intent(hide)`` attribute
     specified will not be listed in the argument list of a wrapper function.
 
@@ -233,11 +231,11 @@ modifications to their source codes are not desirable nor even
 possible.
 
 However, if editing Fortran codes is acceptable, then the generation of an
-intermediate signature file can be skipped in most cases. Namely, F2PY specific
-attributes can be inserted directly to Fortran source codes using the so-called
-F2PY directive. A F2PY directive consists of special comment lines (starting
-with ``Cf2py`` or ``!f2py``, for example) which are ignored by Fortran compilers
-but interpreted by F2PY as normal lines.
+intermediate signature file can be skipped in most cases. F2PY specific
+attributes can be inserted directly into Fortran source codes using F2PY
+directives. A F2PY directive consists of special comment lines (starting with
+``Cf2py`` or ``!f2py``, for example) which are ignored by Fortran compilers but
+interpreted by F2PY as normal lines.
 
 Consider a modified version of the previous Fortran code with F2PY directives,
 saved as ``fib3.f``:

doc/source/f2py/python-usage.rst

@@ -40,9 +40,9 @@ is passed to Fortran routine as a scalar argument.
 
 .. note::
 
-   * When type-casting is required and there is possible loss of
-     information via narrowing (e.g. when type-casting float to integer or complex to
-     float), F2PY *does not* raise an exception.
+   * When type-casting is required and there is possible loss of information via
+     narrowing e.g. when type-casting float to integer or complex to float, F2PY
+     *does not* raise an exception.
 
      * For complex to real type-casting only the real part of a complex number is used.
 
@@ -66,7 +66,7 @@ In Python:
 String arguments
 =================
 
-F2PY generated wrapper functions accept (almost) any Python object as
+F2PY generated wrapper functions accept almost any Python object as
 a string argument, since ``str`` is applied for non-string objects.
 Exceptions are NumPy arrays that must have type code ``'c'`` or
 ``'1'`` when used as string arguments.
@@ -112,12 +112,12 @@ proper type, is used as the array argument.
 
 There are two types of proper-contiguous NumPy arrays:
 
-* Fortran-contiguous arrays refer to when data is stored column-wise,
+* Fortran-contiguous arrays refer to data that is stored columnwise,
   i.e. the indexing of data as stored in memory starts from the lowest
   dimension;
-* C-contiguous or simply contiguous arrays are when data is stored
-  row-wise, i.e. the indexing of data as stored in memory starts from the
-  highest dimension.
+* C-contiguous, or simply contiguous arrays, refer to data that is stored
+  rowwise, i.e. the indexing of data as stored in memory starts from the highest
+  dimension.
 
 For one-dimensional arrays these notions coincide.
 
@@ -220,7 +220,7 @@ and applies a function ``func`` to its elements.
 
 The Fortran code expects that the function ``func`` has been defined externally.
 In order to use a Python function for ``func``, it must have an attribute
-``intent(callback)`` and it must be specified before the ``external`` statement.
+``intent(callback)`` and, it must be specified before the ``external`` statement.
 
 Finally, build an extension module using ``f2py -c -m foo calculate.f``
 

doc/source/f2py/signature-file.rst

@@ -9,8 +9,8 @@ is a subset of Fortran 90/95). F2PY introduces some extensions to the Fortran
 90/95 language specification that help in the design of the Fortran to Python
 interface, making it more "Pythonic".
 
-Signature files may contain arbitrary Fortran code (so that any Fortran 90/95
-codes can be treated as signature files). F2PY silently ignores
+Signature files may contain arbitrary Fortran code so that any Fortran 90/95
+codes can be treated as signature files. F2PY silently ignores
 Fortran constructs that are irrelevant for creating the interface.
 However, this also means that syntax errors are not caught by F2PY and will only
 be caught when the library is built.
@@ -32,9 +32,9 @@ generates.
 
 .. warning::
 
-   Exception: if ``<modulename>`` contains a substring ``__user__``, then
-   the corresponding ``python module`` block describes the signatures of
-   so-called call-back functions (see :ref:`Call-back arguments`).
+   Exception: if ``<modulename>`` contains a substring ``__user__``, then the
+   corresponding ``python module`` block describes the signatures of call-back
+   functions (see :ref:`Call-back arguments`).
 
 A ``python module`` block has the following structure::
 
@@ -59,7 +59,7 @@ A ``python module`` block has the following structure::
 
 Here brackets ``[]`` indicate an optional section, dots ``...`` indicate one or
 more of a previous section. So, ``[]...`` is to be read as zero or more of a
-previous part.
+previous section.
 
 
 Fortran/C routine signatures
@@ -246,12 +246,12 @@ Other statements
 
       .. note::
 
-        Tip: The ``entry`` statement can be used to describe the signature
-        of an arbitrary routine allowing F2PY to generate a number of
+        The ``entry`` statement can be used to describe the signature of an
+        arbitrary subroutine or function allowing F2PY to generate a number of
         wrappers from only one routine block signature. There are few
         restrictions while doing this: ``fortranname`` cannot be used,
-        ``callstatement`` and ``callprotoargument`` can be used only if
-        they are valid for all entry routines, etc.
+        ``callstatement`` and ``callprotoargument`` can be used only if they are
+        valid for all entry routines, etc.
 
 F2PY statements
 ^^^^^^^^^^^^^^^^
@@ -510,9 +510,10 @@ The following attributes are used by F2PY:
 
   .. note::
 
-     If ``check(..)`` is not used then F2PY generates a few standard checks (e.g.
-     in a case of an array argument, it checks for the proper shape and size)
-     automatically. Use ``check()`` to disable checks generated by F2PY.
+     If ``check(..)`` is not used then F2PY automatically generates a few
+     standard checks (e.g.  in a case of an array argument, it checks for the
+     proper shape and size). Use ``check()`` to disable checks
+     generated by F2PY.
 
 ``depend([<names>])``
   This declares that the corresponding argument depends on the values
@@ -537,7 +538,7 @@ The following attributes are used by F2PY:
 
 ``external``
   The corresponding argument is a function provided by user. The
-  signature of this so-called call-back function can be defined
+  signature of this call-back function can be defined
 
   - in ``__user__`` module block,
   - or by demonstrative (or real, if the signature file is a real Fortran
@@ -590,7 +591,7 @@ Extensions
 F2PY directives
 ^^^^^^^^^^^^^^^^
 
-The so-called F2PY directives allow using F2PY signature file constructs in
+The F2PY directives allow using F2PY signature file constructs in
 Fortran 77/90 source codes. With this feature one  can (almost) completely skip
 the intermediate signature file generation and apply F2PY directly to Fortran
 source codes.

doc/source/f2py/usage.rst

@@ -33,13 +33,15 @@ Signature file generation
         [ skip: <fortran functions>  : ]]...            \
        [<fortran files> ...]
 
-   Note that a Fortran source file can contain many routines, and it is often
-   not necessary to allow all routines be usable from Python. So, either specify
-   which routines should be wrapped (in the ``only: .. :`` part) or which routines
-   F2PY should ignored (in the ``skip: .. :`` part).
+   .. note::
+
+    A Fortran source file can contain many routines, and it is often
+    not necessary to allow all routines be usable from Python. In such cases,
+    either specify which routines should be wrapped (in the ``only: .. :`` part)
+    or which routines F2PY should ignored (in the ``skip: .. :`` part).
 
    If ``<filename.pyf>`` is specified as ``stdout`` then signatures
-   are emitted to standard output instead of a file.
+   are written to standard output instead of a file.
 
    Among other options (see below), the following can be used
    in this mode:
@@ -68,7 +70,7 @@ Extension module construction
 
    ``--debug-capi``
      Adds debugging hooks to the extension module. When using this extension
-     module, various diagnostic information about the wrapper is printed to
+     module, various diagnostic information about the wrapper is written to
      the standard output, for example, the values of variables, the steps taken,
      etc.