diff --git a/compiler/res/prog8lib/cx16/psg.p8 b/compiler/res/prog8lib/cx16/psg.p8
index ddf842802..750bddd44 100644
--- a/compiler/res/prog8lib/cx16/psg.p8
+++ b/compiler/res/prog8lib/cx16/psg.p8
@@ -75,8 +75,11 @@ psg {
         ; -- Enables AttackSustainRelease volume envelope for a voice.
         ;    Note: this requires setting up envelopes_irq() as well, read its description.
         ;    voice_num = 0-15   maxvolume = 0-63
-        ;    attack, sustain, release = 0-255 that determine the speed of the A/D/R.
-        ;    TODO describe how the speeds are calculated. For now, experiment. Higher values means *slower* enveloping.
+        ;    attack, sustain, release = 0-255 that determine the speed of the A/D/R:
+        ;    attack time:    MAXVOL/15/attack  seconds.    higher value = faster attack.
+        ;    sustain time:   sustain/60 seconds    higher sustain value = longer sustain (!).
+        ;    release time:   MAXVOL/15/release seconds.   higher vaule = faster release.
+
         envelope_states[voice_num] = 255
         envelope_attacks[voice_num] = attack
         envelope_sustains[voice_num] = sustain
diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst
index a47f7a695..d44c5f892 100644
--- a/docs/source/libraries.rst
+++ b/docs/source/libraries.rst
@@ -383,3 +383,5 @@ Available for the Cx16 target.
 Contains a simple abstraction for the Vera's PSG (programmable sound generator) to play simple waveforms.
 It includes an interrupt routine to handle simple Attack/Release envelopes as well.
 See the examples/cx16/bdmusic.p8  program for ideas how to use it.
+Read the source of this library module for details about the API.
+