--- a/libmlk-core/mlk/core/music.h	Sun Mar 05 10:53:05 2023 +0100
+++ b/libmlk-core/mlk/core/music.h	Sun Mar 05 11:05:40 2023 +0100
@@ -78,7 +78,7 @@
 /**
  * Open a music from a const binary data.
  *
- * The binary data must be kept alive until the font is no longer used.
+ * The binary data must be kept alive until the music is no longer used.
  *
  * \pre music != NULL
  * \pre path != NULL

--- a/libmlk-core/mlk/core/sound.h	Sun Mar 05 10:53:05 2023 +0100
+++ b/libmlk-core/mlk/core/sound.h	Sun Mar 05 11:05:40 2023 +0100
@@ -19,42 +19,123 @@
 #ifndef MLK_CORE_SOUND_H
 #define MLK_CORE_SOUND_H
 
+/**
+ * \file mlk/core/sound.h
+ * \brief Sound support
+ *
+ * This module provides API to play sounds.
+ *
+ * In contrast to music.h module, multiple sounds can be played at a time and
+ * can't be looped.
+ */
+
 #include <stddef.h>
 
-#define MLK_SOUND_CHANNELS_MAX (256)
-
+/**
+ * \struct mlk_music
+ * \brief Music structure
+ *
+ * This structure is non-opaque but has no public fields.
+ */
 struct mlk_sound {
+	/** \cond MLK_PRIVATE_DECLS */
 	void *handle;
-	int channel;
+	/** \endcond MLK_PRIVATE_DECLS */
 };
 
 #if defined(__cplusplus)
 extern "C" {
 #endif
 
+/**
+ * Open a sound file from the file system path.
+ *
+ * \pre music != NULL
+ * \pre path != NULL
+ * \param sound the sound to initialize
+ * \param path the path to the music file (e.g. .ogg, .wav, .mp3, etc)
+ * \return 0 on success or an error code on failure
+ */
 int
-mlk_sound_open(struct mlk_sound *, const char *);
-
-int
-mlk_sound_openmem(struct mlk_sound *, const void *, size_t);
+mlk_sound_open(struct mlk_sound *sound, const char *path);
 
+/**
+ * Open a sound from a const binary data.
+ *
+ * The binary data must be kept alive until the sound is no longer used.
+ *
+ * \pre music != NULL
+ * \pre path != NULL
+ * \param sound the sound to initialize
+ * \param data the font content
+ * \param datasz the font content length
+ * \return 0 on success or an error code on failure
+ */
 int
-mlk_sound_ok(const struct mlk_sound *);
+mlk_sound_openmem(struct mlk_sound *sound, const void *data, size_t datasz);
 
+/**
+ * Tells if the sound structure is usable.
+ *
+ * \param sound the sound to check
+ * \return non-zero if the sound structure is usable
+ */
 int
-mlk_sound_play(struct mlk_sound *);
+mlk_sound_ok(const struct mlk_sound *sound);
 
-void
-mlk_sound_pause(struct mlk_sound *);
+/**
+ * Start playing the sound.
+ *
+ * \pre mlk_sound_ok(sound)
+ * \param sound the sound to play
+ * \return 0 on success or an error code on failure
+ */
+int
+mlk_sound_play(struct mlk_sound *sound);
 
+/**
+ * Pause the sound playback.
+ *
+ * \pre mlk_sound_ok(sound)
+ * \param sound the sound to pause
+ * \sa ::mlk_sound_resume
+ */
 void
-mlk_sound_resume(struct mlk_sound *);
+mlk_sound_pause(struct mlk_sound *sound);
 
+/**
+ * Resume the sound where it was stopped.
+ *
+ * \pre mlk_sound_ok(sound)
+ * \param sound the sound to resume
+ * \sa ::mlk_sound_pause
+ */
 void
-mlk_sound_stop(struct mlk_sound *);
+mlk_sound_resume(struct mlk_sound *sound);
 
+/**
+ * Stop and rewind the sound.
+ *
+ * Calling ::mlk_sound_resume on it will restart from the beginning.
+ *
+ * \pre mlk_sound_ok(sound)
+ * \param sound the sound to stop
+ * \sa ::mlk_sound_resume
+ * \sa ::mlk_sound_play
+ */
 void
-mlk_sound_finish(struct mlk_sound *);
+mlk_sound_stop(struct mlk_sound *sound);
+
+/**
+ * Destroy this sound.
+ *
+ * If the sound is being played, it is stopped immediately.
+ *
+ * \pre mlk_sound_ok(sound)
+ * \param sound the sound to destroy
+ */
+void
+mlk_sound_finish(struct mlk_sound *sound);
 
 #if defined(__cplusplus)
 }