diff --git a/hashes/chaos_machine.py b/hashes/chaos_machine.py
index d2fde2f5e371..8fd2407df9e0 100644
--- a/hashes/chaos_machine.py
+++ b/hashes/chaos_machine.py
@@ -1,17 +1,39 @@
-"""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)
+# --> Stores values undergoing chaotic transformation.
 buffer_space: list[float] = []
+
+# Stores parameters controlling the transformation.
 params_space: list[float] = []
 
 # 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 +61,14 @@ 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