From 42f92396d77bdd2b161a32224c7c5ac9df1c053a Mon Sep 17 00:00:00 2001
From: Matiiss <83066658+Matiiss@users.noreply.github.com>
Date: Thu, 21 Nov 2024 00:16:10 +0200
Subject: [PATCH] document the internal state of sound/music volume

---
 docs/reST/ref/mixer.rst | 28 ++++++++++++++++++++++++++++
 docs/reST/ref/music.rst |  6 ++++++
 2 files changed, 34 insertions(+)

diff --git a/docs/reST/ref/mixer.rst b/docs/reST/ref/mixer.rst
index d23e2aa60a..1357dfc4f0 100644
--- a/docs/reST/ref/mixer.rst
+++ b/docs/reST/ref/mixer.rst
@@ -438,6 +438,25 @@ The following file formats are supported
 
          | If value < 0.0, the volume will not be changed
          | If value > 1.0, the volume will be set to 1.0
+      
+      .. note::
+         The values are internally converted and kept as integer values in range [0, 128], which means
+         that ``get_volume()`` may return a different volume than it was set to. For example,
+
+            >>> sound.set_volume(0.1)
+            >>> sound.get_volume()
+            0.09375
+         
+         This is because when you ``set_volume(0.1)``, the volume is internally calculated like so
+
+            >>> int(0.1 * 128)
+            12
+         
+         This means that some of the precision is lost, so when you retrieve it again using ``get_volume()``,
+         it is converted back to a ``float`` using that integer
+
+            >>> 12 / 128
+            0.09375
 
       .. ## Sound.set_volume ##
 
@@ -448,6 +467,9 @@ The following file formats are supported
 
       Return a value from 0.0 to 1.0 (inclusive) representing the volume for this Sound.
 
+      .. note::
+         See :func:`Sound.set_volume` for more information regarding the returned value
+
       .. ## Sound.get_volume ##
 
    .. method:: get_num_channels
@@ -627,6 +649,9 @@ The following file formats are supported
           sound.set_volume(0.9)   # Now plays at 90% of full volume.
           sound.set_volume(0.6)   # Now plays at 60% (previous value replaced).
           channel.set_volume(0.5) # Now plays at 30% (0.6 * 0.5).
+      
+      .. note::
+         See :func:`Sound.set_volume` for more information regarding how the value is stored internally
 
       .. ## Channel.set_volume ##
 
@@ -641,6 +666,9 @@ The following file formats are supported
       :meth:`Channel.set_volume`. The Sound object also has its own volume
       which is mixed with the channel.
 
+      .. note::
+         See :func:`Sound.set_volume` for more information regarding the returned value
+
       .. ## Channel.get_volume ##
 
    .. method:: get_busy
diff --git a/docs/reST/ref/music.rst b/docs/reST/ref/music.rst
index be4682cc7f..bbf6eb6beb 100644
--- a/docs/reST/ref/music.rst
+++ b/docs/reST/ref/music.rst
@@ -158,6 +158,9 @@ For a complete list of supported file formats, see the :mod:`pygame.mixer` doc p
    volume will remain set at the current level. If the ``volume`` argument
    is greater than ``1.0``, the volume will be set to ``1.0``.
 
+   .. note::
+      See :func:`mixer.Sound.set_volume()<pygame.mixer.Sound.set_volume>` for more information regarding how the value is stored internally
+
    .. ## pygame.mixer.music.set_volume ##
 
 .. function:: get_volume
@@ -168,6 +171,9 @@ For a complete list of supported file formats, see the :mod:`pygame.mixer` doc p
    Returns the current volume for the mixer. The value will be between ``0.0`` 
    and ``1.0``.
 
+   .. note::
+      See :func:`mixer.Sound.set_volume()<pygame.mixer.Sound.set_volume>` for more information regarding the returned value
+
    .. ## pygame.mixer.music.get_volume ##
 
 .. function:: get_busy