Add module-level docstrings and helper utility docstrings

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

pythonbpf/__init__.py

@@ -1,3 +1,10 @@
+"""
+PythonBPF - A Python frontend for eBPF programs.
+
+This package provides decorators and compilation tools to write BPF programs
+in Python syntax and compile them to eBPF bytecode that can run in the kernel.
+"""
+
 from .decorators import bpf, map, section, bpfglobal, struct
 from .codegen import compile_to_ir, compile, BPF
 

pythonbpf/binary_ops.py

@@ -1,3 +1,10 @@
+"""
+Binary operations handling for BPF programs.
+
+This module provides functions to handle binary operations (add, subtract,
+multiply, etc.) and emit the corresponding LLVM IR instructions.
+"""
+
 import ast
 from llvmlite import ir
 from logging import Logger

pythonbpf/codegen.py

@@ -1,3 +1,11 @@
+"""
+Code generation module for PythonBPF.
+
+This module handles the conversion of Python BPF programs to LLVM IR and
+object files. It provides the main compilation pipeline from Python AST
+to BPF bytecode.
+"""
+
 import ast
 from llvmlite import ir
 from .license_pass import license_processing

pythonbpf/decorators.py

@@ -1,3 +1,11 @@
+"""
+Decorators for marking BPF functions, maps, structs, and globals.
+
+This module provides the core decorators used to annotate Python code
+for BPF compilation.
+"""
+
+
 def bpf(func):
     """Decorator to mark a function for BPF compilation."""
     func._is_bpf = True

pythonbpf/expr/__init__.py

@@ -1,3 +1,5 @@
+"""Expression evaluation and processing for BPF programs."""
+
 from .expr_pass import eval_expr, handle_expr
 from .type_normalization import convert_to_bool
 

pythonbpf/expr/expr_pass.py

@@ -1,3 +1,11 @@
+"""
+Expression evaluation and LLVM IR generation.
+
+This module handles the evaluation of Python expressions in BPF programs,
+including variables, constants, function calls, comparisons, boolean
+operations, and more.
+"""
+
 import ast
 from llvmlite import ir
 from logging import Logger

pythonbpf/expr/type_normalization.py

@@ -1,3 +1,10 @@
+"""
+Type normalization and comparison operations for expressions.
+
+This module provides utilities for normalizing types between expressions,
+handling pointer dereferencing, and generating comparison operations.
+"""
+
 from llvmlite import ir
 import logging
 import ast

pythonbpf/functions/__init__.py

@@ -1,3 +1,5 @@
+"""BPF function processing and LLVM IR generation."""
+
 from .functions_pass import func_proc
 
 __all__ = ["func_proc"]

pythonbpf/functions/functions_pass.py

@@ -1,3 +1,11 @@
+"""
+BPF function processing and LLVM IR generation.
+
+This module handles the core function processing, converting Python function
+definitions into LLVM IR for BPF programs. It manages local variables,
+control flow, and statement processing.
+"""
+
 from llvmlite import ir
 import ast
 import logging

pythonbpf/globals_pass.py

@@ -1,3 +1,10 @@
+"""
+Global variables and compiler metadata processing.
+
+This module handles BPF global variables and emits the @llvm.compiler.used
+metadata to prevent LLVM from optimizing away important symbols.
+"""
+
 from llvmlite import ir
 import ast
 

pythonbpf/helper/__init__.py

@@ -1,3 +1,5 @@
+"""BPF helper functions and handlers."""
+
 from .helper_utils import HelperHandlerRegistry
 from .bpf_helper_handler import handle_helper_call
 from .helpers import ktime, pid, deref, XDP_DROP, XDP_PASS

pythonbpf/helper/bpf_helper_handler.py

@@ -1,3 +1,11 @@
+"""
+BPF helper function handlers for LLVM IR emission.
+
+This module provides handlers for various BPF helper functions, emitting
+the appropriate LLVM IR to call kernel BPF helpers like map operations,
+printing, time functions, etc.
+"""
+
 import ast
 from llvmlite import ir
 from enum import Enum

pythonbpf/helper/helper_utils.py

@@ -1,3 +1,11 @@
+"""
+Utility functions for BPF helper function handling.
+
+This module provides utility functions for processing BPF helper function
+calls, including argument handling, string formatting for bpf_printk,
+and a registry for helper function handlers.
+"""
+
 import ast
 import logging
 from collections.abc import Callable
@@ -35,14 +43,36 @@ class HelperHandlerRegistry:
 
 
 def get_var_ptr_from_name(var_name, local_sym_tab):
-    """Get a pointer to a variable from the symbol table."""
+    """
+    Get a pointer to a variable from the symbol table.
+    
+    Args:
+        var_name: Name of the variable to look up
+        local_sym_tab: Local symbol table
+    
+    Returns:
+        Pointer to the variable
+    
+    Raises:
+        ValueError: If the variable is not found
+    """
     if local_sym_tab and var_name in local_sym_tab:
         return local_sym_tab[var_name].var
     raise ValueError(f"Variable '{var_name}' not found in local symbol table")
 
 
 def create_int_constant_ptr(value, builder, int_width=64):
-    """Create a pointer to an integer constant."""
+    """
+    Create a pointer to an integer constant.
+    
+    Args:
+        value: The integer value
+        builder: LLVM IR builder
+        int_width: Width of the integer in bits (default: 64)
+    
+    Returns:
+        Pointer to the allocated integer constant
+    """
     # Default to 64-bit integer
     int_type = ir.IntType(int_width)
     ptr = builder.alloca(int_type)
@@ -52,7 +82,20 @@ def create_int_constant_ptr(value, builder, int_width=64):
 
 
 def get_or_create_ptr_from_arg(arg, builder, local_sym_tab):
-    """Extract or create pointer from the call arguments."""
+    """
+    Extract or create pointer from call arguments.
+    
+    Args:
+        arg: The AST argument node
+        builder: LLVM IR builder
+        local_sym_tab: Local symbol table
+    
+    Returns:
+        Pointer to the argument value
+    
+    Raises:
+        NotImplementedError: If the argument type is not supported
+    """
 
     if isinstance(arg, ast.Name):
         ptr = get_var_ptr_from_name(arg.id, local_sym_tab)
@@ -66,7 +109,21 @@ def get_or_create_ptr_from_arg(arg, builder, local_sym_tab):
 
 
 def get_flags_val(arg, builder, local_sym_tab):
-    """Extract or create flags value from the call arguments."""
+    """
+    Extract or create flags value from call arguments.
+    
+    Args:
+        arg: The AST argument node for flags
+        builder: LLVM IR builder
+        local_sym_tab: Local symbol table
+    
+    Returns:
+        Integer flags value or LLVM IR value
+    
+    Raises:
+        ValueError: If a variable is not found in symbol table
+        NotImplementedError: If the argument type is not supported
+    """
     if not arg:
         return 0
 
@@ -85,7 +142,18 @@ def get_flags_val(arg, builder, local_sym_tab):
 
 
 def simple_string_print(string_value, module, builder, func):
-    """Prepare arguments for bpf_printk from a simple string value"""
+    """
+    Prepare arguments for bpf_printk from a simple string value.
+    
+    Args:
+        string_value: The string to print
+        module: LLVM IR module
+        builder: LLVM IR builder
+        func: The LLVM IR function being built
+    
+    Returns:
+        List of arguments for bpf_printk
+    """
     fmt_str = string_value + "\n\0"
     fmt_ptr = _create_format_string_global(fmt_str, func, module, builder)
 
@@ -101,7 +169,23 @@ def handle_fstring_print(
     local_sym_tab=None,
     struct_sym_tab=None,
 ):
-    """Handle f-string formatting for bpf_printk emitter."""
+    """
+    Handle f-string formatting for bpf_printk emitter.
+    
+    Args:
+        joined_str: AST JoinedStr node representing the f-string
+        module: LLVM IR module
+        builder: LLVM IR builder
+        func: The LLVM IR function being built
+        local_sym_tab: Local symbol table
+        struct_sym_tab: Struct symbol table
+    
+    Returns:
+        List of arguments for bpf_printk
+    
+    Raises:
+        NotImplementedError: If f-string contains unsupported value types
+    """
     fmt_parts = []
     exprs = []
 

pythonbpf/helper/helpers.py

@@ -1,3 +1,11 @@
+"""
+BPF helper function stubs for Python type hints.
+
+This module provides Python stub functions that represent BPF helper functions.
+These stubs are used for type checking and will be replaced with actual BPF
+helper calls during compilation.
+"""
+
 import ctypes
 
 

pythonbpf/license_pass.py

@@ -1,3 +1,10 @@
+"""
+LICENSE global variable processing for BPF programs.
+
+This module handles the processing of the LICENSE function which is required
+for BPF programs to declare their license (typically "GPL").
+"""
+
 from llvmlite import ir
 import ast
 from logging import Logger

pythonbpf/maps/__init__.py

@@ -1,3 +1,5 @@
+"""BPF map types and processing."""
+
 from .maps import HashMap, PerfEventArray, RingBuf
 from .maps_pass import maps_proc
 

pythonbpf/maps/maps.py

@@ -1,3 +1,11 @@
+"""
+BPF map type definitions for Python type hints.
+
+This module provides Python classes that represent BPF map types.
+These are used for type checking and map definition; the actual BPF maps
+are generated as LLVM IR during compilation.
+"""
+
 # This file provides type  and function hints only and does not actually give any functionality.
 class HashMap:
     """

pythonbpf/maps/maps_pass.py

@@ -1,3 +1,10 @@
+"""
+BPF map processing and LLVM IR generation.
+
+This module handles the processing of BPF map definitions decorated with @map,
+converting them to appropriate LLVM IR global variables with BTF debug info.
+"""
+
 import ast
 from logging import Logger
 from llvmlite import ir

pythonbpf/structs/__init__.py

@@ -1,3 +1,5 @@
+"""Struct processing for BPF programs."""
+
 from .structs_pass import structs_proc
 
 __all__ = ["structs_proc"]

pythonbpf/structs/struct_type.py

@@ -1,3 +1,10 @@
+"""
+Struct type wrapper for BPF structs.
+
+This module provides a wrapper class for LLVM IR struct types with
+helper methods for field access and manipulation.
+"""
+
 from llvmlite import ir
 
 

pythonbpf/structs/structs_pass.py

@@ -1,3 +1,10 @@
+"""
+BPF struct processing and LLVM IR type generation.
+
+This module handles the processing of Python classes decorated with @struct,
+converting them to LLVM IR struct types for use in BPF programs.
+"""
+
 import ast
 import logging
 from llvmlite import ir

pythonbpf/type_deducer.py

@@ -1,3 +1,10 @@
+"""
+Type mapping from Python ctypes to LLVM IR types.
+
+This module provides utilities to convert Python ctypes type names
+to their corresponding LLVM IR representations.
+"""
+
 from llvmlite import ir
 
 # TODO: THIS IS NOT SUPPOSED TO MATCH STRINGS :skull: