LibVLC: try to clarify libvlc_media_add_option() limitations

diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h
index f8b267d7f43e2456af3e761fb1c1999d1b96ad88..0489e7d0f582af9245d16546fd372ad4db67989c 100644 (file)
--- a/include/vlc/libvlc_media.h
+++ b/include/vlc/libvlc_media.h
@@ -251,11 +251,13 @@ LIBVLC_API libvlc_media_t *libvlc_media_new_as_node(
  * read the media. This allows to use VLC's advanced
  * reading/streaming options on a per-media basis.
  *
- * The options are detailed in vlc --long-help, for instance
- * "--sout-all". Note that all options are not usable on medias:
- * specifically, due to architectural issues, video-related options
- * such as text renderer options cannot be set on a single media. They
- * must be set on the whole libvlc instance instead.
+ * \note The options are listed in 'vlc --long-help' from the command line,
+ * e.g. "-sout-all". Keep in mind that available options and their semantics
+ * vary across LibVLC versions and builds.
+ * \warning Not all options affects libvlc_media_t objects:
+ * Specifically, due to architectural issues most audio and video options,
+ * such as text renderer options, have no effects on an individual media.
+ * These options must be set through libvlc_new() instead.
  *
  * \param p_md the media descriptor
  * \param ppsz_options the options (as a string)