[vlc-commits] LibVLC: try to clarify libvlc_media_add_option() limitations

[Rémi Denis-Courmont]

vlc | branch: master | Rémi Denis-Courmont <remi at remlab.net> | Sun Dec  9 12:00:04 2012 +0200| [1c42889a352a3f8b2ac355bce07311f17c7b28ea] | committer: Rémi Denis-Courmont

LibVLC: try to clarify libvlc_media_add_option() limitations

> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=1c42889a352a3f8b2ac355bce07311f17c7b28ea
---

 include/vlc/libvlc_media.h |   12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h
index f8b267d..0489e7d 100644
--- 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)