Use OO program terms of 'field' and 'method' to avoid confision of netcdf attribute

Author: wkliao

docs/source/api/attribute_api.rst

@@ -2,10 +2,23 @@
 Attributes
 ===========
 
-NetCDF attributes can be created, accessed, and manipulated using python
-dictionary-like syntax. An attribute can be associated to the file, referred to
-as ``golbal attribute``, as well as to individual variable, referred to as
-``variable's attribute``. Pythonic interfaces for accessing attributes are is
-provided both in :class:`pnetcdf.File` (for global attributes) and the
-:class:`pnetcdf.Variable` (for variable attributes).
+In `object-oriented programming <https://en.wikipedia.org/wiki/Object-oriented_programming>`_,
+a class contains fields (state variables containing data) and methods
+(subroutines or procedures defining the object's behavior in code). ``Fields``
+may also be known as members, attributes, or properties. To avoid confusion
+with NetCDF's terminology of ``attribute``, this document uses `field` to refer
+to a class's state variable.
+
+NetCDF attributes are small, supplementary metadata that annotates variables or
+files.  NetCDF attribute is not a Python class by itself. Instead, it is a
+field of python dictionary in class :class:`pnetcdf.File` and class
+:class:`pnetcdf.Variable`.  Their data types can be any allowed by the classic
+NetCDF file formats.  The most common data type is `text` for annotation
+purpose.  NetCDF attributes can be created, accessed, and manipulated using
+python dictionary-like syntax.  An attribute can be associated to a file,
+referred to as ``golbal attribute``, as well as to individual variables,
+referred to as ``variable's attribute``.  Pythonic interfaces for accessing
+attributes are is provided both in class :class:`pnetcdf.File` (for global
+attributes) and class :class:`pnetcdf.Variable` (for variable attributes).
+Example programs are `examples/global_attribute.py` and `examples/put_var.py`.
 

docs/source/api/dimension_api.rst

@@ -11,13 +11,13 @@ dimensions objects stored in the file.
    :members: getfile, isunlimited
    :exclude-members: name, size
 
-Read-only Python Attributes of Dimension Class
- The following class members are read-only and should not be modified by the
+Read-only python fields of class :class:`pnetcdf.Dimension`
+ The following class fields are read-only and should not be modified by the
  user.
 
  .. attribute:: name
 
-    String name of Dimension instance. This class member is read-only and
+    String name of Dimension instance. This class field is read-only and
     should not be modified by the user. To rename a dimension, use
     :meth:`File.rename_dim` method.
 

docs/source/api/file_api.rst

@@ -17,8 +17,8 @@ of data and relations among data objects stored in a netCDF file.
     inq_header_size, inq_put_size, inq_header_extent, inq_nreqs
    :exclude-members: dimensions, variables, file_format, indep_mode, path
 
-Read-only Python Attributes of File Class
- The following class members are read-only and should not be modified by the
+Read-only python fields of class :class:`pnetcdf.File`
+ The following class fields are read-only and should not be modified by the
  user.
 
    .. attribute:: dimensions

docs/source/api/function_api.rst

@@ -1,7 +1,10 @@
 ================
-Other PnetCDF Utility Functions
+Other pnetcdf class methods
 ================
 
+   PnetCDF class methods listed below are not associated with particular
+   instances of ``File`` or ``Variable``.
+
 .. autofunction:: pnetcdf::libver
 .. autofunction:: pnetcdf::strerror
 .. autofunction:: pnetcdf::strerrno

docs/source/api/variable_api.rst

@@ -20,8 +20,8 @@ syntax.
     chartostring
 
 
-Read-only Python Attributes of Variable Class
-    The following class members are read-only and should not be modified
+Read-only python fields of class :class:`pnetcdf.Variable`
+    The following class fields are read-only and should not be modified
     directly by the user.
 
     .. attribute:: name

docs/source/index.rst

@@ -43,7 +43,7 @@ netCDF files.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Copyright Statement
+   :caption: Copyright
 
    copyright
 

docs/source/tutorial/basic.rst

@@ -80,7 +80,8 @@ Dimensions
 
  To retrieve the previous defined dimension instance from the file, you can
  directly index the dictionary using variable name as the key.  The dimension
- information can be retrieved using following functions.
+ information can be retrieved using following python functions or ``Dimension``
+ class methods.
 
  .. code-block:: Python
 

docs/source/tutorial/compare_netcdf4.rst

@@ -20,22 +20,21 @@ Difference in Programming Model
 
  Data/Define Mode
   NetCDF4-python library automatically switches between data and define mode
-  for the user by calling ``redef`` and ``enddef`` internally within the
-  define-mode operation functions. For performance reason, this is **not**
-  adopted in Pnetcdf-python. A manual call to :meth:`File.redef` is compulsory
-  to re-enter the define mode, following the C library convention. Similarly,
-  :meth:`File.enddef` is required before switching to data mode operations.
-  This design is based on considerations of the following aspects:
+  by calling ``redef`` and ``enddef`` internally.  For performance reason, this
+  is **not** adopted in Pnetcdf-python. A manual call to :meth:`File.redef` is
+  compulsory to re-enter the define mode, following the C library convention.
+  Similarly, :meth:`File.enddef` is required before switching to data mode
+  operations.  This design is based on considerations of the following aspects:
 
   - Minimize overheads during consecutive define operations: Automatically
-    wrapping all define functions with :meth:`File.redef` and
+    wrapping all define methods with :meth:`File.redef` and
     :meth:`File.enddef` could introduce significant overhead between
     consecutive define operations. The netCDF4-python approach results in
     unnecessary data/define mode switches, impacting performance.
 
   - Avoid potential hanging when performing independent I/O: if
-    :meth:`File.enddef` is automatically embedded in all data mode operation
-    functions, the program will hang when partial processes are performing
+    :meth:`File.enddef` is automatically embedded in all data mode
+    methods, the program will hang when partial processes are performing
     independent I/O (while others don't) because :meth:`File.enddef` is a
     collective call which requires all processes to participate.
 

src/pnetcdf/_Dimension.pyx

@@ -89,7 +89,7 @@ cdef class Dimension:
 
     def __str__(self):
         if not dir(self._file):
-            return 'Dimension object no longer valid'
+            return 'Dimension is not valid'
         if self.isunlimited():
             return "%r (unlimited): name = '%s', size = %s" %\
                 (type(self), self._name, len(self))
@@ -110,8 +110,7 @@ cdef class Dimension:
         """
         getfile(self)
 
-        :return: the ``pnetcdf.File`` instance that this ``Dimension`` is a
-            member of.
+        :return: the ``pnetcdf.File`` instance that this ``Dimension`` belongs to.
 
         :rtype: :class:`pnetcdf.File`
         """

src/pnetcdf/_File.pyx

@@ -63,7 +63,7 @@ cdef class File:
         :type comm: mpi4py.MPI.Comm or None
 
         :param info: [Optional]
-            MPI info object to use for file access. `None` defaults to
+            MPI info instance to use for file access. `None` defaults to
             ``MPI_INFO_NULL``.
         :type info: mpi4py.MPI.Info or None
 
@@ -178,7 +178,7 @@ cdef class File:
 
 
     def __dealloc__(self):
-        # close file when there are no references to object left
+        # close file when there are no references to it left
         if self._isopen:
            self._close(False)
 
@@ -296,8 +296,8 @@ cdef class File:
         must be a positive integer or `-1`, which stands for "unlimited"
         (default is `-1`). The return value is the `Dimension` class instance
         describing the new dimension.  To determine the current maximum size of
-        the dimension, use the `len` function on the `Dimension` instance. To
-        determine if a dimension is 'unlimited', use the
+        the dimension, use the python function `len()` on the `Dimension`
+        instance. To determine if a dimension is 'unlimited', use the
         :meth:`Dimension.isunlimited` method of the `Dimension` instance.
 
         :param str dimname: Name of the new dimension.
@@ -454,7 +454,7 @@ cdef class File:
         # # containing all the netCDF attribute name/value pairs is provided by
         # # the `__dict__` attribute of a `Variable` instance.
 
-        # # `Variable` instances behave much like array objects. Data can be
+        # # `Variable` instances behave much like arrays. Data can be
         # # assigned to or retrieved from a variable with indexing and slicing
         # # operations on the `Variable` instance. A `Variable` instance has six
         # # Dataset standard attributes: `dimensions, dtype, shape, ndim, name`.
@@ -925,10 +925,10 @@ cdef class File:
         """
         set_auto_chartostring(self, value)
 
-        Call :meth:`Variable.set_auto_chartostring` for all variables
-        contained in this `File`. Calling this function only affects existing
-        variables.  Variables defined after calling this function will follow
-        the default behaviour.
+        Call :meth:`Variable.set_auto_chartostring` for all variables contained
+        in this `File`. Calling this method only affects existing variables.
+        Variables defined after calling this method will follow the default
+        behaviour.
 
         :param value: True or False
         :type value: bool
@@ -1026,7 +1026,7 @@ cdef class File:
         """
         inq_info(self)
 
-        Returns an MPI info object containing all the file hints used by
+        Returns an MPI info instance containing all the file hints used by
         PnetCDF library.
 
         :rtype:  mpi4py.MPI.Info
@@ -1106,7 +1106,7 @@ cdef class File:
         return extent
 
 cdef _get_dims(file):
-    # Private function to create `Dimension` instances for all the
+    # Private method to create `Dimension` instances for all the
     # dimensions in a `File`
     cdef int ierr, numdims, n, _file_id
     cdef int *dimids
@@ -1132,7 +1132,7 @@ cdef _get_dims(file):
     return dimensions
 
 cdef _get_variables(file):
-    # Private function to create `Variable` instances for all the
+    # Private method to create `Variable` instances for all the
     # variables in a `File`
     cdef int ierr, numvars, n, nn, numdims, varid, classp, iendian, _file_id
     cdef int *varids

src/pnetcdf/_Variable.pyx

@@ -34,8 +34,7 @@ ctypedef MPI.Datatype Datatype
 cdef class Variable:
     """
     A PnetCDF variable is used to read and write netCDF data.  They are
-    analogous to numpy array objects. See :meth:`Variable.__init__` for more
-    details.
+    analogous to numpy arrays. See :meth:`Variable.__init__` for more details.
 
     .. note:: ``Variable`` instances should be created using the
         :meth:`File.def_var` method of a :meth:`File` instance, not using this
@@ -102,7 +101,7 @@ cdef class Variable:
         self._file = file
         _file_id = self._file_id
         #TODO: decide whether we need to check xtype at python-level
-        if isinstance(datatype, str): # convert to numpy datatype object
+        if isinstance(datatype, str): # convert to numpy data type object
             datatype = np.dtype(datatype)
         if isinstance(datatype, np.dtype):
             if datatype.str[1:] in _supportedtypes:
@@ -161,7 +160,8 @@ cdef class Variable:
 
     def __array__(self):
         # numpy special method that returns a numpy array.
-        # allows numpy ufuncs to work faster on Variable objects
+        # This allows numpy Universal functions ufuncs to work faster on
+        # Variable instances.
         return self[...]
 
     def __repr__(self):
@@ -526,11 +526,10 @@ cdef class Variable:
         self.chartostring = bool(chartostring)
 
     def __getitem__(self, elem):
-        # This special method is used to index the netCDF variable
-        # using the "extended slice syntax". The extended slice syntax
-        # is a perfect match for the "start", "count" and "stride"
-        # arguments to the ncmpi_get_var() function, and is much more easy
-        # to use.
+        # This special method is used to index the netCDF variable using the
+        # "extended slice syntax". The extended slice syntax is a perfect match
+        # for the "start", "count" and "stride" arguments to the C function
+        # ncmpi_get_var(), and is much more easy to use.
         start, count, stride, put_ind =\
         _StartCountStride(elem,self.shape,dimensions=self.dimensions,file=self._file)
         datashape = _out_array_shape(count)
@@ -593,11 +592,10 @@ cdef class Variable:
         return data
 
     def __setitem__(self, elem, data):
-        # This special method is used to assign to the netCDF variable
-        # using "extended slice syntax". The extended slice syntax
-        # is a perfect match for the "start", "count" and "stride"
-        # arguments to the ncmpi_put_var() function, and is much more easy
-        # to use.
+        # This special method is used to assign to the netCDF variable using
+        # "extended slice syntax". The extended slice syntax is a perfect match
+        # for the "start", "count" and "stride" arguments to the C function
+        # ncmpi_put_var(), and is much more easy to use.
 
         # if _Encoding is specified for a character variable, convert
         # numpy array of strings to a numpy array of characters with one more