Improve playlist documentation regarding callbacks.

Doxygen documentation now mentions that the playlist library will set the preset switch callbacks in projectM and needs them to function properly. Added hints on how to restore functionality if needed.

src/playlist/api/projectM-4/playlist_core.h

@@ -36,11 +36,18 @@ extern "C" {
 /**
  * @brief Creates a playlist manager for the given projectM instance
  *
- * Only one active playlist manager is supported per projectM instance. If multiple playlists use
+ * <p>Only one active playlist manager is supported per projectM instance. If multiple playlists use
  * the same projectM instance, only the last created playlist manager will receive preset change
- * callbacks from the projectM instance.
+ * callbacks from the projectM instance.</p>
  *
- * To switch to another playlist, use the projectm_playlist_connect() method.
+ * <p>To switch to another playlist, use the <tt>projectm_playlist_connect()</tt> method.</p>
+ *
+ * @important <p>If the projectM handle is not NULL, this method will register the playlist manager with the
+ *            <tt>projectm_preset_switch_requested_event</tt> and <tt>projectm_preset_switch_failed_event</tt> callbacks
+ *            of the referenced projectM instance. Setting any one of those callbacks to another function pointer
+ *            afterwards will cause the playlist manager to no longer being able to switch presets.</p>
+ *            <p>If the callback needs to be changed temporarily, the playlist functionality can be restored by calling
+ *            <tt>projectm_playlist_connect()</tt>, which will re-register the callbacks.</p>
  *
  * @param projectm_instance The projectM instance to connect to. Can be a null pointer to leave the newly
  *                          created playlist instance unconnected.
@@ -52,7 +59,9 @@ PROJECTM_PLAYLIST_EXPORT projectm_playlist_handle projectm_playlist_create(proje
 /**
  * @brief Destroys a previously created playlist manager.
  *
- * If the playlist manager is currently connected to a projectM instance, it will be disconnected.
+ * If the playlist manager is currently connected to a projectM instance, it will be disconnected
+ * by resetting the <tt>projectm_preset_switch_requested_event</tt> and
+ * <tt>projectm_preset_switch_failed_event</tt> callbacks to NULL.
  *
  * @param instance The playlist manager instance to destroy.
  * @since 4.0.0
@@ -62,14 +71,21 @@ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_destroy(projectm_playlist_handle
 /**
  * @brief Connects the playlist manager to a projectM instance.
  *
- * Sets or removes the preset switch callbacks and stores the projectM instance handle for use with
- * manual preset switches via the playlist API.
+ * <p>Sets or removes the preset switch callbacks and stores the projectM instance handle for use with
+ * manual preset switches via the playlist API.</p>
  *
- * When switching between multiple playlist managers, first call this method on the last used
+ * <p>When switching between multiple playlist managers, first call this method on the last used
  * playlist manager with a null pointer for the projectM instance, then call this method with the
  * actual projectM instance on the playlist manager that should be activated. It is also safe to
- * call projectm_playlist_connect() with a null projectM handle on all playlist manager instances
- * before activating a single one with a valid, non-null projectM handle.
+ * call <tt>projectm_playlist_connect()</tt> with a null projectM handle on all playlist manager instances
+ * before activating a single one with a valid, non-null projectM handle.</p>
+ *
+ * @important <p>If the projectM handle is not NULL, this method will register the playlist manager with the
+ *            <tt>projectm_preset_switch_requested_event</tt> and <tt>projectm_preset_switch_failed_event</tt> callbacks
+ *            of the referenced projectM instance. Setting any one of those callbacks to another function pointer
+ *            afterwards will cause the playlist manager to no longer being able to switch presets.</p>
+ *            <p>If the callback needs to be changed temporarily, the playlist functionality can be restored by calling
+ *            <tt>projectm_playlist_connect()</tt>, which will re-register the callbacks.</p>
  *
  * @param instance The playlist manager instance.
  * @param projectm_instance The projectM instance to connect to. Can be a null pointer to remove