docs: a small refactor of the Documentation + adding hints to sections 1-6 of the Documentation

Author: n1xsi

README.md

@@ -95,7 +95,7 @@ pip install pycustomrand
 
 
 ## 📚 Документация
-Ниже представлено описание всех доступных функций библиотеки. Для удобства они могут импороваться напрямую из пакета (`from pycustomrand import FUNC_NAME`).
+Ниже представлено описание всех доступных функций библиотеки с примерами. Для удобства они могут импороваться напрямую из пакета (`from pycustomrand import FUNC_NAME`).
 
 ### 1. Управление состоянием (Seeding)
 Инициализация генератора позволяет получать воспроизводимые последовательности (например, для тестов или сохранения генерации мира).
@@ -107,6 +107,24 @@ pip install pycustomrand
 * `_get_next_seed_state(current_seed)`
 Внутренняя функция для обновления состояния сида (LCG алгоритм).
 
+<details>
+    <summary>🧩 Примеры 1</summary>
+  
+```python
+from pycustomrand import set_seed, random
+
+print(random())  # Случайное число, например, 0.3730190220377659
+
+set_seed("test")  # Установление сида для тестов
+print(random())   # Первый результат функции после установления сида "test" ВСЕГДА будет 0.1647608190844912
+print(random())   # Второй результат функции тоже ВСЕГДА будет 0.943716375817365 (применилась функция _get_next_seed_state(current_seed="test"))
+
+set_seed()       # Обнуление сида
+print(random())  # Случайное число, например, 0.2458062256227575
+```
+
+</details>
+
 ### 2. Целые числа
 * `gen_random_number(length=1)`
 Генерирует число заданной длины `length`, склеивая случайные цифры.
@@ -118,6 +136,27 @@ pip install pycustomrand
 Возвращает случайное целое число `N`, такое что `start <= N <= end` (**обе границы включены**).
   * `step`: Шаг генерации. Например, `step=2` вернет только чётные (или нечётные) числа. Необязательный аргумент.
 
+<details>
+    <summary>🧩 Примеры 2</summary>
+  
+```python
+from pycustomrand import gen_random_number, randrange, random_integer
+
+print(gen_random_number(5))  # Случайное число длиной 5, например: 92103
+
+print(randrange(10))        # Случайное число из диапазона [0, 10)
+print(randrange(1, 10))     # Случайное число из диапазона [1, 10)
+print(randrange(0, 10, 2))  # Случайное чётное число из диапазона [0, 10)
+
+print(random_integer(1, 10))     # Случайное целое число из диапазона [1, 10]
+print(random_integer(0, 10, 2))  # Случайное чётное целое число из диапазона [0, 10]
+
+# randint - алиас для random_integer, работает при "import pycustomrand", "from pycustomrand import *" или "from pycustomrand import randint"
+# randint(1, 10) равноценно random_integer(1, 10)
+```
+
+</details>
+
 ### 3. Вещественные числа
 * `random()`
 Возвращает случайное число `float` в диапазоне `[0.0, 1.0)`.
@@ -127,6 +166,20 @@ pip install pycustomrand
   * `start`, `end`: Начало и конец диапазона, могут быть как целыми числами, так и числами с плавающей точкой.
   * `digits`: Если число указано, результат будет округлён до этого количества знаков с помощью `true_round`.
 
+<details>
+    <summary>🧩 Примеры 3</summary>
+  
+```python
+from pycustomrand import random, random_float
+
+print(random())  # Случайное число в диапазоне [0, 1), например 0.2260351121787103
+
+print(random_float(0, 10))            # Случайное число с плавающей точкой в диапазоне [0, 10), например 4.014874483651235
+print(random_float(0, 10, digits=3))  # То же самое, только с округлением до 3-ёх знаков, например 6.722
+```
+
+</details>
+
 ### 4. Последовательности
 * `choice(array)`
 Возвращает один случайный элемент из последовательности.
@@ -142,6 +195,30 @@ pip install pycustomrand
 Возвращает список из `k` **уникальных** случайных элементов.
   * `counts`: Список с количеством повторений для каждого элемента массива (соответствует по индексу).
 
+<details>
+    <summary>🧩 Примеры 4</summary>
+  
+```python
+from pycustomrand import choice, choices, shuffle, sample
+
+array = ["apple", "banana", "cherry", "orange"]
+
+print(choice(array))  # Случайный элемент из массива, например "cherry"
+
+print(choices(array, k=2))  # Список из k случайных элементов из массива, например ['apple', 'cherry']
+print(choices(array, k=2, weights=[1, 2, 3, 4]))  # Список из k случайных элементов из массива с весами, например ['orange', 'banana']
+# "orange" (с весом 4) будет выпдать в четыре раза чаще, чем "apple" (с весом 1)
+
+shuffle(array)  # Перемешивает массив на месте
+print(array)    # Например ['cherry', 'banana', 'apple', 'orange']
+
+print(sample(array, k=2))  # Список из k уникальных случайных элементов из массива, например ['cherry', 'apple']
+print(sample(array, k=2, counts=[1, 2, 3, 4]))  # Список из k уникальных случайных элементов из массива с весами, например ['banana', 'orange']
+# "orange" (с количеством в массиве 4) будет выпдать в четыре раза больше, чем "apple" (количество в массиве 1)
+```
+
+</details>
+
 ### 5. Вероятностные распределения
 Эти функции используются для моделирования реальных процессов (физика, экономика, игры).
 
@@ -164,15 +241,56 @@ pip install pycustomrand
 Количество успехов в серии из `n` независимых испытаний с вероятностью успеха `p`.
 Используется в моделировании финансов и математике. *Примеры*: Сколько раз сейчас выпадет орёл, если подбросить монету 10 раз — `binomialvariate(n=10, p=0.5)`.
 
+<details>
+    <summary>🧩 Примеры 5</summary>
+  
+```python
+from pycustomrand import triangular, gauss, expovariate, binomialvariate
+
+print(triangular(low=0.0, high=1.0, mode=0.5))  # Случайное число с плавающей точкой из треугольного распределения (диапазон [0.0, 1.0])
+# Чаще всего выпадает значение ±0.5, например: 0.6508330793068139
+
+print(gauss(mu=0.0, sigma=1.0))  # Случайное число с плавающей точкой из нормального "колокольного" распределения (общий диапазон 0.0 ± ~3.0)
+# Чаще всего выпадает значение 0.0 ± 1.0, например: 1.0665809173007805 или -1.650128903962443
+
+print(expovariate(lambd=1.0))  # Случайное число с плавающей точкой из экспоненциального распределения (общий диапазон 0.0 ± ~4.0)
+# Чаще всего выпадает наименьшее значение от 0.0 до 1.0, например: 0.405175514533143
+
+print(binomialvariate(n=10, p=0.5))  # Случайное число из биномиального распределения (диапазон [0, 10]), например: 5
+# Чем меньше вероятность p - тем чаще будет выпадать число из первой половины диапазона [0, 10], больше - большее из второй половины
+
+# binomial - алиас для binomialvariate, работает при "import pycustomrand", "from pycustomrand import *" или "from pycustomrand import binomial"
+# binomial(n=10, p=0.5)) равноценно binomialvariate(n=10, p=0.5)
+```
+
+</details>
+
 ### 6. Утилиты (Extras)
-* `random_uuid4()`: Генерация уникального идентификатора (UUID v4), например, `f47ac10b-58cc-4372-a567-0e02b2c3d479`. 
+* `random_bytes(count)`: Генерация случайных байт в количестве `count`.
 
-* `random_color_hex()`: Случайный цвет в формате HEX, например, #a1f4e0.
+* `random_uuid4()`: Генерация уникального идентификатора (UUID v4). 
 
-* `random_bytes(count)`: Генерация count случайных байт, например, `random_bytes(10)` выдаст `b'\x8ag\x16p\xddK|\x11(\x83'`.
+* `random_color_hex()`: Случайный цвет в формате HEX.
 
 * `random_bool(true_chance=0.5)`: Возвращает True или False c вероятностью `true_chance`.
 
+<details>
+    <summary>🧩 Примеры 6</summary>
+  
+```python
+from pycustomrand import random_bytes, random_uuid4, random_color_hex, random_bool
+
+print(random_bytes(10))    # Случайные 10 байтов, например: b'\x8b\x91\x19\xe42\xcd\x80\x82b\xba'
+
+print(random_uuid4())      # Случайный UUID v4, например: '0e1d2eeb-1627-4cfa-8130-afe74e1c5ce9'
+
+print(random_color_hex())  # Cлучайный цвет в формате hex, например: '#0ca3e7'
+
+print(random_bool())       # Случайное значение True/False, например: True
+```
+
+</details>
+
 ### 🎯 О модуле `true_round`
 Модуль решает проблему "банковского округления" в Python 3, где `round(x.5)` округляется до ближайшего чётного числа.
 `true_round` использует **честное математическое округление** (отсюда и название "true" — истинное/честное).