Doc update for residue validity and connectivity.

modules/mol/base/doc/entity.rst

@@ -118,7 +118,13 @@ The Handle Classes
     an enabled ``USE_NUMPY`` flag (see :ref:`here <cmake-flags>` for details).
 
     :type: :class:`numpy.array`
-  
+
+  .. attribute:: valid
+
+    Validity of handle.
+
+    :type: bool
+
   .. method:: GetName()
 
     :returns: Name associated to this entity.
@@ -327,6 +333,10 @@ The Handle Classes
     :type radius: float
     
     :returns: :class:`AtomHandleList` (list of :class:`AtomHandle`)
+
+  .. method:: IsValid()
+  
+    See :attr:`valid`
     
 .. class:: ChainHandle
 
@@ -424,6 +434,12 @@ The Handle Classes
     :meth:`GetCenterOfAtoms`.
     
     :type: :class:`~ost.geom.Vec3`
+
+  .. attribute:: valid
+
+    Validity of handle.
+
+    :type: bool
     
   .. method:: FindResidue(res_num)
    
@@ -469,6 +485,10 @@ The Handle Classes
 
     See :attr:`description`
 
+  .. method:: IsValid()
+  
+    See :attr:`valid`
+
 .. class:: ResidueHandle
 
   The residue is either used to represent complete molecules or building blocks 
@@ -625,8 +645,6 @@ The Handle Classes
     Central atom used for rendering traces. For peptides, this is usually
     the CA atom. For nucleotides, this is usually the P atom.
 
-    Also available as :meth:`GetCentralAtom` and :meth:`SetCentralAtom`.
-
     :type: :class:`AtomHandle`
 
   .. attribute:: central_normal
@@ -635,10 +653,30 @@ The Handle Classes
     nucleotides if all required atoms available. Otherwise, the (1,0,0) vector
     is returned.
 
-    Read-only. Also available as :meth:`GetCentralNormal`.
-
     :type: :class:`~ost.geom.Vec3`
 
+  .. attribute:: valid
+
+    Validity of handle.
+
+    :type: bool
+
+  .. attribute:: next
+
+    Residue after this one in the same chain. Invalid handle returned if there
+    is no next residue. Residues are ordered as in :attr:`ChainHandle.residues`
+    independently on whether they are connected or not (see
+    :func:`InSequence` to check for connected residues).
+
+    :type: :class:`ResidueHandle`
+
+  .. attribute:: prev
+
+    Residue before this one in the same chain. Otherwise same behaviour as
+    :attr:`next`.
+
+    :type: :class:`ResidueHandle`
+
   .. method:: FindAtom(atom_name)
 
     Get atom by atom name. See also :attr:`atoms`
@@ -693,8 +731,12 @@ The Handle Classes
 
   .. method:: GetCentralNormal()
     
-    See :attr:`index`
+    See :attr:`central_normal`
+
+  .. method:: IsValid()
   
+    See :attr:`valid`
+
 
 .. class:: AtomHandle
 
@@ -811,6 +853,12 @@ The Handle Classes
 
     :type: int
 
+  .. attribute:: valid
+
+    Validity of handle.
+
+    :type: bool
+
   .. method:: FindBondToAtom(other_atom)
 
     Finds and returns the bond formed between this atom and `other_atom`. If no 
@@ -928,8 +976,7 @@ The Handle Classes
   .. method:: IsValid()
   
     See :attr:`valid`
-  
-    :rtype: bool
+
   
 The View Classes
 --------------------------------------------------------------------------------
@@ -1010,6 +1057,12 @@ The View Classes
      
      :type: :class:`EntityHandle`
 
+  .. attribute:: valid
+
+     Validity of view.
+
+     :type: bool
+
   .. method:: GetName()
 
     :returns: :func:`~EntityHandle.GetName` of entity :attr:`handle`.
@@ -1271,6 +1324,10 @@ The View Classes
     
     See :attr:`atom_count`
 
+  .. method:: IsValid()
+  
+    See :attr:`valid`
+
 .. class:: ChainView
 
   A view representation of a :class:`ChainHandle`. Mostly, the same
@@ -1380,7 +1437,7 @@ The View Classes
 
   .. attribute:: valid
 
-     Validity of handle.
+     Validity of view.
 
      :type: bool
 
@@ -1782,6 +1839,28 @@ Other Entity-Related Functions
 
   :returns: :class:`EntityHandle`
 
+.. function:: InSequence(res, res_next)
+
+  :return: True, if both *res* and *res_next* are :attr:`~ResidueHandle.valid`,
+           *res_next* is the residue following *res* (see 
+           :attr:`ResidueHandle.next`), both residues are linking (i.e.
+           :attr:`~ChemClass.IsPeptideLinking` or
+           :attr:`~ChemClass.IsNucleotideLinking`) and are connected by an
+           appropriate bond.
+  :rtype:  :class:`bool`
+  :param res: First residue to check.
+  :type res:  :class:`ResidueHandle`
+  :param res_next: Second residue to check.
+  :type res_next:  :class:`ResidueHandle`
+
+.. function:: BondExists(atom_a, atom_b)
+
+  :return: True, if *atom_a* and *atom_b* are connected by a bond.
+  :rtype:  :class:`bool`
+  :param atom_a: First atom to check.
+  :type atom_a:  :class:`AtomHandle`
+  :param atom_b: Second atom to check.
+  :type atom_b:  :class:`AtomHandle`
 
 Residue Numbering
 --------------------------------------------------------------------------------