diff --git a/hashes/chaos_machine.py b/hashes/chaos_machine.py
index d2fde2f5e371..f6ce6f863b72 100644
--- a/hashes/chaos_machine.py
+++ b/hashes/chaos_machine.py
@@ -1,17 +1,30 @@
-"""example of simple chaos machine"""
+"""example of simple chaos machine
+Simple Chaos Machine refers to computational model that demonstrates chaotic behavior.
+It takes input values, applies a chaotic transformation using control theory principles, and generates
+unpredictable output ( meaning small changes in input lead to drastically different outputs over time),"""
+
+""" Chaos Machine (K, t, m)
+    K --> Initial values for the buffer space.
+    t --> Time length for evolution (how long transformations happen).
+    m --> Number of elements in the chaotic system."""
 
-# Chaos Machine (K, t, m)
 K = [0.33, 0.44, 0.55, 0.44, 0.33]
 t = 3
 m = 5
 
-# Buffer Space (with Parameters Space)
+# Buffer Space (with Parameters Space) --> Stores values undergoing chaotic transformation.
 buffer_space: list[float] = []
+
+# Stores parameters controlling the transformation.
 params_space: list[float] = []
 
-# Machine Time
+# Machine Time --> Keeps track of execution time.
 machine_time = 0
 
+"""The push() function updates the buffer_space and params_space by applying chaotic transformations
+based on control theory. It modifies all values in the buffer_space using an orbit change and trajectory change formula,
+which ensure values to stay within controlled chaotic limits. Finally, it increments machine_time."""
+
 
 def push(seed):
     global buffer_space, params_space, machine_time, K, m, t
@@ -39,6 +52,11 @@ def push(seed):
     machine_time += 1
 
 
+"""The pull() function generates a chaotic pseudo-random number using a logistic map transformation
+and the Xorshift algorithm. It updates buffer_space and params_space over multiple iterations, ensuring chaotic evolution.
+Finally, it selects two chaotic values, applies Xorshift, and returns a 32-bit random number."""
+
+
 def pull():
     global buffer_space, params_space, machine_time, K, m, t