feat: add detailed docstrings for rotatable bond functions and utility methods

rotatable_bonds.py

@@ -1,3 +1,9 @@
+"""
+Module for identifying and visualizing rotatable bonds in molecular structures.
+Provides functionality to detect single bonds that can rotate using both
+a local algorithm and SMARTS pattern matching approaches.
+"""
+
 from rdkit import Chem
 from utils import mol_to_svg, highlight_by_patterns, IMAGE_SIZE
 
@@ -8,6 +14,21 @@ rotatable_patterns = {
 }
 
 def get_rotatable_bond_indices(mol):
+    """
+    Identifies rotatable bonds in a molecule using local structural analysis.
+    
+    A bond is considered rotatable if it:
+    - Is a single bond
+    - Is not in a ring
+    - Neither atom is a hydrogen
+    - Both atoms have at least 2 neighbors
+    
+    Args:
+        mol: RDKit molecule object
+    
+    Returns:
+        list: Indices of rotatable bonds in the molecule
+    """
     rot_bond_indices = []
     for bond in mol.GetBonds():
         if bond.GetBondType() != Chem.BondType.SINGLE:
@@ -24,6 +45,16 @@ def get_rotatable_bond_indices(mol):
     return rot_bond_indices
 
 def highlight_rotatable_bonds(smiles: str):
+    """
+    Creates an SVG visualization of a molecule with rotatable bonds highlighted.
+    
+    Args:
+        smiles: SMILES string representation of the molecule
+    
+    Returns:
+        str: SVG string of the molecule with rotatable bonds highlighted, or
+             None if no rotatable bonds are found or if SMILES is invalid
+    """
     mol = Chem.MolFromSmiles(smiles)
     if mol is None:
         return None
@@ -34,6 +65,18 @@ def highlight_rotatable_bonds(smiles: str):
     return img
 
 def process_rotatable(smiles: str):
+    """
+    Processes a molecule to identify rotatable bonds using multiple methods
+    and generates visualizations for each method.
+    
+    Args:
+        smiles: SMILES string representation of the molecule
+    
+    Returns:
+        tuple: (list of (image, caption) tuples, status message string)
+               Images show the molecule with rotatable bonds highlighted using
+               different detection methods
+    """
     images = []
     img = highlight_rotatable_bonds(smiles)
     if img:

utils.py

@@ -1,11 +1,30 @@
-# utils.py
+"""
+Utility functions for molecular visualization and pattern matching using RDKit.
+Provides SVG rendering capabilities and substructure highlighting functionality.
+"""
+
 from rdkit import Chem
 from rdkit.Chem.Draw import MolDraw2DSVG
 import tempfile
 
 IMAGE_SIZE = (400, 400)
 
-def mol_to_svg(mol, size, highlightAtoms=None, highlightBonds=None, legend="", atomLabels=None):
+def mol_to_svg(mol: Chem.Mol, size: tuple[int, int], highlightAtoms: list[int] = None, 
+               highlightBonds: list[int] = None, legend: str = "", atomLabels: dict[int, str] = None) -> str:
+    """
+    Converts an RDKit molecule to an SVG image file with optional highlighting and labels.
+
+    Args:
+        mol: RDKit molecule object to render
+        size: Tuple of (width, height) for the output image
+        highlightAtoms: List of atom indices to highlight
+        highlightBonds: List of bond indices to highlight
+        legend: Text to display as image legend
+        atomLabels: Dictionary mapping atom indices to label strings
+
+    Returns:
+        str: Path to the temporary SVG file containing the rendered molecule
+    """
     drawer = MolDraw2DSVG(size[0], size[1])
     opts = drawer.drawOptions()
     
@@ -23,7 +42,18 @@ def mol_to_svg(mol, size, highlightAtoms=None, highlightBonds=None, legend="", a
     tmp.close()
     return tmp.name
 
-def highlight_by_patterns(smiles: str, pattern_dict: dict):
+def highlight_by_patterns(smiles: str, pattern_dict: dict[str, Chem.Mol]) -> list[tuple[str, str]]:
+    """
+    Generates visualizations of a molecule with substructures matching SMARTS patterns highlighted.
+
+    Args:
+        smiles: SMILES string representation of the molecule
+        pattern_dict: Dictionary mapping pattern names to RDKit molecule objects representing SMARTS patterns
+
+    Returns:
+        list: List of tuples containing (image_path, pattern_name) for each matching pattern.
+              Returns None if the SMILES string is invalid.
+    """
     mol = Chem.MolFromSmiles(smiles)
     if mol is None:
         return None