Clarify the metadata functionality of QMediaPlayer.

By linking to QMediaObject functions.  Also clean that up a bit so it's
a bit more useful for people looking for higher level functionality.

Change-Id: Ie452122c4d55f88326a7b71c5882dfe38f489791
Reviewed-by: Angus Cummings <angus.cummings@nokia.com>
Reviewed-by: Ling Hu <ling.hu@nokia.com>
Reviewed-by: Dmytro Poplavskiy <dmytro.poplavskiy@nokia.com>
Reviewed-by: Daniel Kovacic <daniel.kovacic@nokia.com>

src/multimedia/playback/qmediaplayer.cpp

@@ -68,8 +68,8 @@ QT_BEGIN_NAMESPACE
 
     The QMediaPlayer class is a high level media playback class. It can be used
     to playback such content as songs, movies and internet radio. The content
-    to playback is specified as a QMediaContent, which can be thought of as a
+    to playback is specified as a QMediaContent object, which can be thought of as a
-    main or canonical URL with addition information attached. When provided
+    main or canonical URL with additional information attached. When provided
     with a QMediaContent playback may be able to commence.
 
     \snippet doc/src/snippets/multimedia-snippets/media.cpp Player
@@ -79,6 +79,14 @@ QT_BEGIN_NAMESPACE
 
     \snippet doc/src/snippets/multimedia-snippets/media.cpp Movie playlist
 
+    Since QMediaPlayer is a QMediaObject, you can use several of the QMediaObject
+    functions for things like:
+
+    \list
+    \li Accessing the currently playing media's metadata (\l {QMediaObject::metaData()} and \l predefined \l {QtMultimedia::MetaData}{meta-data keys})
+    \li Checking to see if the media playback service is currently available (\l {QMediaObject::availabilityError()})
+    \endlist
+
     \sa QMediaObject, QMediaService, QVideoWidget, QMediaPlaylist
 */
 

src/multimedia/qmediaobject.cpp

@@ -85,17 +85,20 @@ void QMediaObjectPrivate::_q_availabilityChanged()
     \ingroup multimedia
     \ingroup multimedia_core
 
+    It provides some basic functionality that is common to other high level classes
+    like \l QMediaPlayer, \l QAudioDecoder and \l QCamera, including availability
+    and meta-data functionality, as well as functionality to connect media objects
+    with support classes like QMediaPlaylist.
 
-    QMediaObject derived classes provide access to the functionality of a
+    The higher level QMediaObject derived classes provide the actual multimedia
-    QMediaService.  Each media object hosts a QMediaService and uses the
+    functionality, by internally using a QMediaService.  Each media object
-    QMediaControl interfaces implemented by the service to implement its
+    hosts a QMediaService and uses the QMediaControl interfaces implemented by the service to implement its
-    API.  Most media objects when constructed will request a new
+    API.  These controls can be accessed from the media object if necessary, but in general
-    QMediaService instance from a QMediaServiceProvider, but some like
+    the useful functionality can be accessed from the higher level classes.
-    QMediaRecorder will share a service with another object.
 
-    QMediaObject itself provides an API for accessing a media
+    Most media objects when constructed will request a new
-    service's \l {metaData()}{meta-data} and a means of connecting other media objects,
+    QMediaService instance, but some like
-    and peripheral classes like QVideoWidget and QMediaPlaylist.
+    QMediaRecorder and QAudioRecorder will share a service with another object.
 
     \sa QMediaService, QMediaControl
 */
@@ -338,6 +341,8 @@ bool QMediaObject::isMetaDataAvailable() const
 
 /*!
     Returns the value associated with a meta-data \a key.
+
+    See the list of predefined \l {QtMultimedia::MetaData}{meta-data keys}.
 */
 QVariant QMediaObject::metaData(const QString &key) const
 {