Add docstrings to core modules and helper functions

Co-authored-by: varun-r-mallya <100590632+varun-r-mallya@users.noreply.github.com>

pythonbpf/maps/maps.py

@@ -1,18 +1,51 @@
 # This file provides type  and function hints only and does not actually give any functionality.
 class HashMap:
+    """
+    A BPF hash map for storing key-value pairs.
+    
+    This is a type hint class used during compilation. The actual BPF map
+    implementation is generated as LLVM IR.
+    """
+    
     def __init__(self, key, value, max_entries):
+        """
+        Initialize a HashMap definition.
+        
+        Args:
+            key: The ctypes type for keys (e.g., c_int64)
+            value: The ctypes type for values (e.g., c_int64)
+            max_entries: Maximum number of entries the map can hold
+        """
         self.key = key
         self.value = value
         self.max_entries = max_entries
         self.entries = {}
 
     def lookup(self, key):
+        """
+        Look up a value by key in the map.
+        
+        Args:
+            key: The key to look up
+        
+        Returns:
+            The value if found, None otherwise
+        """
         if key in self.entries:
             return self.entries[key]
         else:
             return None
 
     def delete(self, key):
+        """
+        Delete an entry from the map by key.
+        
+        Args:
+            key: The key to delete
+        
+        Raises:
+            KeyError: If the key is not found in the map
+        """
         if key in self.entries:
             del self.entries[key]
         else:
@@ -20,6 +53,17 @@ class HashMap:
 
     # TODO: define the flags that can be added
     def update(self, key, value, flags=None):
+        """
+        Update or insert a key-value pair in the map.
+        
+        Args:
+            key: The key to update
+            value: The new value
+            flags: Optional flags for update behavior
+        
+        Raises:
+            KeyError: If the key is not found in the map
+        """
         if key in self.entries:
             self.entries[key] = value
         else:
@@ -27,25 +71,76 @@ class HashMap:
 
 
 class PerfEventArray:
+    """
+    A BPF perf event array for sending data to userspace.
+    
+    This is a type hint class used during compilation.
+    """
+    
     def __init__(self, key_size, value_size):
+        """
+        Initialize a PerfEventArray definition.
+        
+        Args:
+            key_size: The size/type for keys
+            value_size: The size/type for values
+        """
         self.key_type = key_size
         self.value_type = value_size
         self.entries = {}
 
     def output(self, data):
+        """
+        Output data to the perf event array.
+        
+        Args:
+            data: The data to output
+        """
         pass  # Placeholder for output method
 
 
 class RingBuf:
+    """
+    A BPF ring buffer for efficient data transfer to userspace.
+    
+    This is a type hint class used during compilation.
+    """
+    
     def __init__(self, max_entries):
+        """
+        Initialize a RingBuf definition.
+        
+        Args:
+            max_entries: Maximum number of entries the ring buffer can hold
+        """
         self.max_entries = max_entries
 
     def reserve(self, size: int, flags=0):
+        """
+        Reserve space in the ring buffer.
+        
+        Args:
+            size: Size in bytes to reserve
+            flags: Optional reservation flags
+        
+        Returns:
+            0 as a placeholder (actual implementation is in BPF runtime)
+        
+        Raises:
+            ValueError: If size exceeds max_entries
+        """
         if size > self.max_entries:
             raise ValueError("size cannot be greater than set maximum entries")
         return 0
 
     def submit(self, data, flags=0):
+        """
+        Submit data to the ring buffer.
+        
+        Args:
+            data: The data to submit
+            flags: Optional submission flags
+        """
         pass
 
     # add discard, output and also give names to flags and stuff

pythonbpf/maps/maps_pass.py

@@ -20,6 +20,15 @@ def maps_proc(tree, module, chunks):
 
 
 def is_map(func_node):
+    """
+    Check if a function node is decorated with @map.
+    
+    Args:
+        func_node: The AST function node to check
+    
+    Returns:
+        True if the function is decorated with @map, False otherwise
+    """
     return any(
         isinstance(decorator, ast.Name) and decorator.id == "map"
         for decorator in func_node.decorator_list
@@ -65,7 +74,17 @@ class BPFMapType(Enum):
 
 
 def create_bpf_map(module, map_name, map_params):
-    """Create a BPF map in the module with given parameters and debug info"""
+    """
+    Create a BPF map in the module with given parameters and debug info.
+    
+    Args:
+        module: The LLVM IR module to add the map to
+        map_name: The name of the BPF map
+        map_params: Dictionary of map parameters (type, key_size, value_size, max_entries)
+    
+    Returns:
+        The created global variable representing the map
+    """
 
     # Create the anonymous struct type for BPF map
     map_struct_type = ir.LiteralStructType(