Doc: Improved example documentation

-added instructions on how to run the example
 (using \include to insert a section from qtbase/doc/global/)
-updated copyright year
-removed links to Qt 4 API
-rearranged some of the sections
-created links from the example pages to Qt Multimedia
-fixed QDoc warnings related to the example pages

Task-number: QTBUG-33597
Change-Id: Id45ce5cbd40dbfa384abd7260a316f6f6837c186
Reviewed-by: Yoann Lopes <yoann.lopes@digia.com>
Reviewed-by: Sze Howe Koh <szehowe.koh@gmail.com>

examples/multimedia/audiodevices/doc/src/audiodevices.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -29,8 +29,8 @@
     \example audiodevices
     \title Audio Devices Example
     \ingroup multimedia_examples
-    \brief The Audio Devices example shows the application of the audio devices APIs
+    \brief The Audio Devices example shows the application of the audio devices
-
+    APIs.
 
     This example shows how to create a simple application to list and test
     the configuration for the various audio devices available on the device
@@ -38,6 +38,5 @@
 
     \image audiodevices.png
 
+    \include examples-run.qdocinc
 */
-
-

examples/multimedia/audioengine/doc/src/audioengine.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -30,10 +30,10 @@
     \title AudioEngine Example
     \ingroup multimedia_examples
     \brief The Audio Engine example demonstrates 3D sound control using
-    the QtAudioEngine API.
+    the Qt Audio Engine API.
 
-    \image audioengine.png
+    The Audio Engine example demonstrates 3D sound control using the
+    \l{Qt Audio Engine QML Types}{Qt Audio Engine} API.
 
+    \include examples-run.qdocinc
 */
-
-

examples/multimedia/audioinput/doc/src/audioinput.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -37,7 +37,8 @@
     Qt provides the QAudioInput class to enable audio functionality within
     a standard application user interface.
 
-    This example calculates the maximum linear value of the input audio from the microphone and displays the output.
+    This example calculates the maximum linear value of the input audio from the
+    microphone and displays the output.
+
+    \include examples-run.qdocinc
 */
-
-

examples/multimedia/audiooutput/doc/src/audiooutput.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -31,13 +31,14 @@
     \ingroup multimedia_examples
     \brief The Audio Output Example show the use of the QAudioOutput API.
 
-    The example demonstrates the basic use cases of the QAudioOutput class.
+    The example demonstrates the basic use cases of the QAudioOutput class from
+    \l{Qt Multimedia}.
 
     \image audiooutput-example.png
 
     This example provides a tone generator to supply continuous audio playback.
     The first button allows pause and resume of the playback, and the second
     button allows toggling between push and pull modes of operation.
+
+    \include examples-run.qdocinc
 */
-
-

examples/multimedia/audiorecorder/doc/src/audiorecorder.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -34,6 +34,12 @@
     It demonstrates the discovery of the supported devices and codecs and the use
     of recording functions in the QAudioRecorder class.
 
+    \image audiorecorder.png
+
+    \include examples-run.qdocinc
+
+    \section1 Displaying the Window and Audio Settings
+
     We display a window for the user to select the appropriate audio input,
     codec, container, and sample rate. Allow a setting of either quality or
     bitrate. Finally, the output file can be selected and recording can be
@@ -49,7 +55,7 @@
     \l{QMultimedia::NormalQuality}, while the bitrates are hardcoded
     into the list.
 
-    \image audiorecorder.png
+    \section1 Recording Audio
 
     To record audio we simply create a QAudioRecorder object.
 
@@ -96,5 +102,3 @@
     ui->statusbar->showMessage(tr("Recorded %1 sec").arg(duration / 1000));
     \endcode
 */
-
-

examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -34,35 +34,22 @@ or video.
 
 \image qml-camera.png
 
-This example demonstrates how to use the Qt Multimedia QML API to access
+This example demonstrates how to use the
-camera functions. It shows how to change settings and to capture images.
+\l{Qt Multimedia QML Types}{Qt Multimedia QML API} to access camera functions.
+It shows how to change settings and to capture images.
+
+\include examples-run.qdocinc
+
+\section1 Application Structure
 
 Most of the QML code supports the user interface for this application with the
 camera types being mostly found in \e {declarative-camera.qml} and
 \e {CaptureControls.qml}.
 
-In \e {declarative-camera.qml} the \l Camera is initialized with an id
+CaptureControls, which is implemented in \e {CaptureControls.qml},
-of \e {camera}, a photo preview is setup, states are implemented for image
-preview or capture and \l CaptureControls is initialized. The initial
-\e state is \e PhotoCapture. \l CameraCapture includes a handler, \e onImageCaptured,
-for the \l {imageCaptured} signal. The handler sets up the application to process
-the preview including a change in the user interface state. The \l PhotoPreview
-becomes visible with any key press being picked up by the handler
-in PhotoPreview and returning the state to \e PhotoCapture.
-
-\e CaptureControls, which is implemented in \e {CaptureControls.qml},
 generates a column on the right hand side of the screen which includes control
-buttons for \e focus (not initially visible), \e {capture}, \e {flash modes},
+buttons for focus (not initially visible), capture, flash modes,
-\e {white balance}, \e {exposure compensation}, and if a preview is
+white balance, exposure compensation, and if a preview is
-available a \e {preview} button. The last button exits from the application.
+available, a preview button. The last button exits from the application.
-
-When the Capture button is pressed the \e onClicked handler calls
-\l {Camera::captureImage()}{captureImage()}
-
-
-
-
-
-
 
 */

examples/multimedia/declarative-radio/doc/src/declarative-radio.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -31,8 +31,8 @@
     \brief Demonstrates the radio functionality
     \ingroup multimedia_examples
 
-    This examples uses the Qt Multimedia Radio QML type to list the available
+    This examples uses the \l{Qt Multimedia} \l Radio QML type to list the
-    channels on the FM frequency.
+    available channels on the FM frequency.
+
+    \include examples-run.qdocinc
 */
-
-

examples/multimedia/spectrum/doc/src/spectrum.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -59,6 +59,6 @@
     (FFT) of a segment of audio data.  An open-source library,
     \l{http://ldesoras.free.fr/prod.html}{FFTReal}, against which the
     application is dynamically linked, is used to compute the transform.
+
+    \include examples-run.qdocinc
 */
-
-

examples/multimedia/video/doc/src/qmlvideo.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -34,8 +34,6 @@
 resize; rotate; change aspect ratio) which can be applied to QML \l{VideoOutput}
 items.
 
-\section1 Overview
-
 This example demonstrates the various manipulations (move; resize; rotate;
 change aspect ratio) which can be applied to QML \l{VideoOutput} items.
 
@@ -50,7 +48,9 @@ which moves across the \l{VideoOutput} item.
 
 \image qmlvideo-overlay.png
 
-\section1 Application structure
+\include examples-run.qdocinc
+
+\section1 Application Structure
 
 The \l{video/qmlvideo/qml/qmlvideo/main.qml} file creates a UI which includes
 the following items:
@@ -127,7 +127,7 @@ instance, the embedded
 \l{video/qmlvideo/qml/qmlvideo/Content.qml}{Content} item creates either a
 \l{MediaPlayer} or a \l{Camera} item.
 
-\section1 Calculating and displaying QML painting rate
+\section1 Calculating and Displaying QML Painting Rate
 
 \input multimedia/doc/src/examples/video-qml-paint-rate.qdocinc
 
@@ -145,4 +145,3 @@ object to a JavaScript function, which will eventually call frequencyItem.notify
 \printuntil SLOT(qmlFramePainted()));
 
 */
-

examples/multimedia/video/doc/src/qmlvideofx.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -34,9 +34,11 @@
 can be used to apply postprocessing effects, expressed in \c GLSL, to video
 and camera viewfinder content.
 
+\include examples-run.qdocinc
+
 \section1 Overview
 
-This example shows how a \l {ShaderEffectItem} can be used to apply
+This example shows how a \l {ShaderEffect} can be used to apply
 postprocessing effects, expressed in GLSL, to QML \l {VideoOutput} items.
 
 It also shows how native code can be combined with QML to implement more
@@ -73,7 +75,7 @@ for Effect*.qml files in the list above to see the full range.
 \section1 Application structure
 
 Shader effects can be applied to video or viewfinder content using
-\l{ShaderEffectItem}, as shown in the following example, which applies
+\l{ShaderEffect}, as shown in the following example, which applies
 a wiggly effect to the content:
 
 \code
@@ -171,7 +173,7 @@ is based on the \l{ShaderEffect}:
 \skipto import
 \printuntil /^\}/
 
-The interface of the \l Effect allows for derived effects to specify the
+The interface of Effect allows for derived effects to specify the
 number of parameters which they support (and therefore the number of sliders
 which should be displayed), and whether a vertical dividing line should be drawn
 between transformed and untransformed image regions.  As an example, here is the
@@ -219,4 +221,3 @@ object to a JavaScript function, which will eventually call frequencyItem.notify
 \printuntil SLOT(qmlFramePainted()));
 
 */
-

examples/multimediawidgets/camera/doc/src/camera.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -35,10 +35,12 @@
 \brief  The Camera Example shows how to use the API to capture a still image
 or video.
 
-The Camera Example demonstrates how you can use Qt Multimedia to implement
+The Camera Example demonstrates how you can use \l{Qt Multimedia} to implement
 some basic Camera functionality to take still images and record video clips
 with audio.
 
+\include examples-run.qdocinc
+
 A Camera class is created that will act as our Camera. It has a user interface,
 control functions, setting values and a means of defining the location where
 the image or video clip is to be saved. It will also store the image and video
@@ -74,5 +76,3 @@ is started with a call to \l {QMediaRecorder::record()}.
 \image camera-example.png
 
 */
-
-

examples/multimediawidgets/player/doc/src/player.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -34,6 +34,8 @@
     This example creates a simple multimedia player. We can play audio and
     or video files using various codecs.
 
+    \include examples-run.qdocinc
+
     The example uses a QMediaPlayer object passed into a QVideoWidget to
     control the video output. To give the application playlist capability
     we also use a QPlayList object.
@@ -93,4 +95,3 @@
     \endcode
 
 */
-

examples/multimediawidgets/videographicsitem/doc/src/videographicsitem.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -32,9 +32,11 @@
 \brief This example demonstrates how to stream video on a graphics scene.
 
     The Video Graphics Item example shows how to implement a QGraphicsItem that displays video on a
-    graphics scene using Qt Multimedia's QAbstractVideoSurface.
+    graphics scene using \l{Qt Multimedia}'s QAbstractVideoSurface.
 
     \image video-videographicsitem.png
 
     \sa {Video Widget Example}
+
+    \include examples-run.qdocinc
 */

examples/multimediawidgets/videowidget/doc/src/videowidget.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -32,7 +32,9 @@
     \brief This example is a simple video player
 
     The Video Widget example denonstrates how to implement a video widget using
-    Qt Multimedia's QAbstractVideoSurface.
+    \l{Qt Multimedia}'s QAbstractVideoSurface.
 
     \image video-videowidget.png
+
+    \include examples-run.qdocinc
 */