Small documentation improvements

chemfiles/frame.py

@@ -93,15 +93,15 @@ def add_atom(self, atom, position, velocity=None):
             velocity = chfl_vector3d(velocity[0], velocity[1], velocity[2])
         self.ffi.chfl_frame_add_atom(self.mut_ptr, atom.ptr, position, velocity)
 
-    def remove(self, i):
+    def remove(self, index):
         """
-        Remove the atom at index ``i`` in this :py:class:`Frame`.
+        Remove the atom at the given ``index`` in this :py:class:`Frame`.
 
-        This modify all the atoms indexes after ``i``, and invalidate any array
-        obtained using :py:func:`Frame.positions` or
-        :py:func:`Frame.velocities`.
+        This shifts all the atoms indexes larger than ``index`` by 1  (``n``
+        becomes ``n - 1``); and invalidate any array obtained using
+        :py:func:`Frame.positions` or :py:func:`Frame.velocities`.
         """
-        self.ffi.chfl_frame_remove(self.mut_ptr, c_uint64(i))
+        self.ffi.chfl_frame_remove(self.mut_ptr, c_uint64(index))
 
     def add_bond(self, i, j, order=None):
         """
@@ -229,17 +229,17 @@ def topology(self, topology):
     @property
     def step(self):
         """
-        Get this :py:class:`Frame` step, i.e. the frame number in the
+        Get the step of this :py:class:`Frame`, i.e. the frame number in the
         trajectory.
         """
         step = c_uint64()
         self.ffi.chfl_frame_step(self.ptr, step)
         return step.value
 
     @step.setter
-    def step(self, step):
-        """Set this :py:class:`Frame` step to ``step``."""
-        self.ffi.chfl_frame_set_step(self.mut_ptr, c_uint64(step))
+    def step(self, value):
+        """Set the step for this :py:class:`Frame` to the given ``value``."""
+        self.ffi.chfl_frame_set_step(self.mut_ptr, c_uint64(value))
 
     def guess_bonds(self):
         """
@@ -252,29 +252,29 @@ def guess_bonds(self):
 
     def distance(self, i, j):
         """
-        Get the distance between the atoms at indexes ``i`` and ``j`` in this
-        :py:class:`Frame`, accounting for periodic boundary conditions. The
-        result is expressed in angstroms.
+        Get the distance (in Ångströms) between the atoms at indexes ``i`` and
+        ``j`` in this :py:class:`Frame`, taking periodic boundary conditions
+        into account.
         """
         distance = c_double()
         self.ffi.chfl_frame_distance(self.ptr, c_uint64(i), c_uint64(j), distance)
         return distance.value
 
     def angle(self, i, j, k):
         """
-        Get the angle formed by the atoms at indexes ``i``, ``j`` and ``k`` in
-        this :py:class:`Frame`, accounting for periodic boundary conditions.
-        The result is expressed in radians.
+        Get the angle (in radians) formed by the atoms at indexes ``i``, ``j``
+        and ``k`` in this :py:class:`Frame`, taking periodic boundary conditions
+        into account.
         """
         angle = c_double()
         self.ffi.chfl_frame_angle(self.ptr, c_uint64(i), c_uint64(j), c_uint64(k), angle)
         return angle.value
 
     def dihedral(self, i, j, k, m):
         """
-        Get the dihedral angle formed by the atoms at indexes ``i``, ``j``,
-        ``k`` and ``m`` in this :py:class:`Frame`, accounting for periodic
-        boundary conditions. The result is expressed in radians.
+        Get the dihedral angle (in radians) formed by the atoms at indexes
+        ``i``, ``j``, ``k`` and ``m`` in this :py:class:`Frame`, taking periodic
+        boundary conditions into account.
         """
         dihedral = c_double()
         self.ffi.chfl_frame_dihedral(
@@ -284,9 +284,9 @@ def dihedral(self, i, j, k, m):
 
     def out_of_plane(self, i, j, k, m):
         """
-        Get the out of plane distance formed by the atoms at indexes ``i``,
-        ``j``, ``k`` and ``m`` in this :py:class:`Frame`, accounting for
-        periodic boundary conditions. The result is expressed in angstroms.
+        Get the out of plane distance (in Ångströms) formed by the atoms at
+        indexes ``i``, ``j``, ``k`` and ``m`` in this :py:class:`Frame`, taking
+        periodic boundary conditions into account.
 
         This is the distance betweent the atom j and the ikm plane. The j atom
         is the center of the improper dihedral angle formed by i, j, k and m.

chemfiles/selection.py

@@ -18,7 +18,7 @@ class Selection(CxxPointer):
     ``== != < <= > >=``. Refer to the `full documentation
     <selections-doc>`_ to know the allowed selectors and how to use them.
 
-    .. selections-doc: http://chemfiles.rtfd.io/en/latest/selections.html
+    .. selections-doc: https://chemfiles.org/chemfiles/latest/selections.html
     """
 
     def __init__(self, selection):

chemfiles/topology.py

@@ -69,10 +69,11 @@ def __repr__(self):
 
     def remove(self, index):
         """
-        Remove the :py:class:`Atom` atthe given ``index`` from the associated
+        Remove the :py:class:`Atom` at the given ``index`` from the associated
         :py:class:`Topology`.
 
-        This shifts all the atoms indexes after ``i`` by 1 (n becomes n-1).
+        This shifts all the atoms indexes larger than ``index`` by 1  (``n``
+        becomes ``n - 1``);
         """
         self.topology.ffi.chfl_topology_remove(self.topology.mut_ptr, c_uint64(index))
 

chemfiles/trajectory.py

@@ -10,19 +10,19 @@
 
 class Trajectory(CxxPointer):
     """
-    A :py:class:`Trajectory` is a chemistry file on the hard drive. It is the
-    main entry point of Chemfiles.
+    A :py:class:`Trajectory` represent a physical file from which we can read
+    :py:class:`Frame`.
     """
 
     def __init__(self, path, mode="r", format=""):
         """
-        Open the :py:class:`Trajectory` at the given ``path`` using the
-        given ``mode`` and optional specific file ``format``.
+        Open the file at the given ``path`` using the given ``mode`` and
+        optional file ``format``.
 
         Valid modes are ``'r'`` for read, ``'w'`` for write and ``'a'`` for
         append.
 
-        The specific file format is needed when the file format does not match
+        The ``format`` parameter is needed when the file format does not match
         the extension, or when there is not standard extension for this format.
         If `format` is an empty string, the format will be guessed from the
         file extension.
@@ -61,7 +61,7 @@ def __repr__(self):
 
     def read(self):
         """
-        Read the next step of the :py:class:`Trajectory` and return the
+        Read the next step of this :py:class:`Trajectory` and return the
         corresponding :py:class:`Frame`.
         """
         self.__check_opened()
@@ -71,7 +71,7 @@ def read(self):
 
     def read_step(self, step):
         """
-        Read a specific ``step`` in the :py:class:`Trajectory` and return the
+        Read a specific ``step`` in this :py:class:`Trajectory` and return the
         corresponding :py:class:`Frame`.
         """
         self.__check_opened()
@@ -80,23 +80,24 @@ def read_step(self, step):
         return frame
 
     def write(self, frame):
-        """Write a :py:class:`Frame` to the :py:class:`Trajectory`."""
+        """Write a :py:class:`Frame` to this :py:class:`Trajectory`."""
         self.__check_opened()
         self.ffi.chfl_trajectory_write(self.mut_ptr, frame.ptr)
 
     def set_topology(self, topology, format=""):
         """
-        Set the :py:class:`Topology` associated with a :py:class:`Trajectory`.
-        This :py:class:`Topology` will be used when reading and writing the
-        files, replacing any :py:class:`Topology` in the frames or files.
+        Set the :py:class:`Topology` associated with this :py:class:`Trajectory`.
 
-        If ``topology`` is a :py:class:`Topology` instance, it is used
-        directly. If ``topology`` is a string, the first :py:class:`Frame` of
-        the corresponding file is read, and the topology of this frame is used.
+        The new topology will be used when reading and writing the files,
+        replacing any topology in the frames or files.
 
-        When reading from a file, if ``format`` is not the empty string, the
-        code uses this file format instead of guessing it from the file
-        extension.
+        If the ``topology`` parameter is a :py:class:`Topology` instance, it is
+        used directly. If the ``topology`` parameter is a string, the first
+        :py:class:`Frame` of the corresponding file is read, and the topology of
+        this frame is used.
+
+        When reading from a file, if ``format`` is not the empty string, it is
+        used as the file format instead of guessing it from the file extension.
         """
         self.__check_opened()
         if isinstance(topology, Topology):
@@ -108,36 +109,35 @@ def set_topology(self, topology, format=""):
 
     def set_cell(self, cell):
         """
-        Set the :py:class:`UnitCell` associated with a :py:class:`Trajectory`.
+        Set the :py:class:`UnitCell` associated with this :py:class:`Trajectory`
+        to a copy of ``cell``.
+
         This :py:class:`UnitCell` will be used when reading and writing the
-        files, replacing any :py:class:`UnitCell` in the frames or files.
+        files, replacing any unit cell in the frames or files.
         """
         self.__check_opened()
         self.ffi.chfl_trajectory_set_cell(self.mut_ptr, cell.ptr)
 
     @property
     def nsteps(self):
-        """
-        Get the number of steps (the number of frames) in a
-        :py:class:`Trajectory`.
-        """
+        """Get the current number of steps in this :py:class:`Trajectory`."""
         self.__check_opened()
         nsteps = c_uint64()
         self.ffi.chfl_trajectory_nsteps(self.mut_ptr, nsteps)
         return nsteps.value
 
     @property
     def path(self):
-        """Get the path used to open this  :py:class:`Trajectory`."""
+        """Get the path used to open this :py:class:`Trajectory`."""
         self.__check_opened()
         path = c_char_p()
         self.ffi.chfl_trajectory_path(self.ptr, path)
         return path.value.decode('utf-8')
 
     def close(self):
         """
-        Close the :py:class:`Trajectory` and write any buffered content to the
-        hard drive.
+        Close this :py:class:`Trajectory` and write any buffered content to the
+        file.
         """
         self.__check_opened()
         self.__closed = True