diff --git a/hashes/chaos_machine.py b/hashes/chaos_machine.py
index d2fde2f5e371..450a507bf861 100644
--- a/hashes/chaos_machine.py
+++ b/hashes/chaos_machine.py
@@ -1,18 +1,38 @@
-"""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 +59,13 @@ 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
 
@@ -99,4 +126,4 @@ def reset():
         print(f"{format(pull(), '#04x')}")
         print(buffer_space)
         print(params_space)
-        inp = input("(e)exit? ").strip()
+        inp = input("(e)exit? ").strip()
\ No newline at end of file