Documentation and whitespace fixes in phonon

 - fix wrong copy/pasted comments (including the whole docs for isSeekable)
 - make docs of Notifier more generic (there are 3 signals, not just one)
 - untabify

Merge-request: 875
Reviewed-by: Leonardo Sobral Cunha <leo.cunha@nokia.com>

5 files changed, 46 insertions, 51 deletions

diff --git a/src/3rdparty/phonon/ds9/backend.cpp b/src/3rdparty/phonon/ds9/backend.cpp
index 245749aab1..2c56af7837 100644
--- a/src/3rdparty/phonon/ds9/backend.cpp
+++ b/src/3rdparty/phonon/ds9/backend.cpp
@@ -50,7 +50,7 @@ namespace Phonon
         Backend::Backend(QObject *parent, const QVariantList &)
             : QObject(parent)
         {
-			::CoInitialize(0);
+            ::CoInitialize(0);
 
             //registering meta types
             qRegisterMetaType<HRESULT>("HRESULT");
@@ -61,7 +61,7 @@ namespace Phonon
         {
             m_audioOutputs.clear();
             m_audioEffects.clear();
-			::CoUninitialize();
+            ::CoUninitialize();
         }
 
         QObject *Backend::createObject(BackendInterface::Class c, QObject *parent, const QList<QVariant> &args)
@@ -216,7 +216,7 @@ namespace Phonon
                     LPOLESTR str = 0;
                     HRESULT hr = mon->GetDisplayName(0,0, &str);
                     if (SUCCEEDED(hr)) {
-                        QString name = QString::fromUtf16((unsigned short*)str); 
+                        QString name = QString::fromUtf16((unsigned short*)str);
 						ComPointer<IMalloc> alloc;
 						::CoGetMalloc(1, alloc.pparam());
                         alloc->Free(str);
diff --git a/src/3rdparty/phonon/ds9/mediaobject.cpp b/src/3rdparty/phonon/ds9/mediaobject.cpp
index f77bdc1612..df42011368 100644
--- a/src/3rdparty/phonon/ds9/mediaobject.cpp
+++ b/src/3rdparty/phonon/ds9/mediaobject.cpp
@@ -36,7 +36,7 @@ along with this library.  If not, see <http://www.gnu.org/licenses/>.
 
 #include <QtCore/QDebug>
 
-#define TIMER_INTERVAL 16 //... ms for the timer that polls the current state (we use the multimedia timer
+#define TIMER_INTERVAL 16 //... ms for the timer that polls the current state (we use the multimedia timer)
 #define PRELOAD_TIME 2000 // 2 seconds to load a source
 
 QT_BEGIN_NAMESPACE
@@ -89,7 +89,7 @@ namespace Phonon
                 DWORD result = ::WaitForMultipleObjects(count, handles, FALSE, INFINITE);
                 if (result == WAIT_OBJECT_0) {
                     if (m_finished) {
-                        //that's the end if the thread execution
+                        //that's the end of the thread execution
                         return;
                     }
 
@@ -210,7 +210,7 @@ namespace Phonon
             {
                 QMutexLocker locker(&m_mutex);
                 m_currentRender = w.graph;
-			    m_currentRenderId = w.id;
+                m_currentRenderId = w.id;
             }
 
             if (w.task == ReplaceGraph) {
@@ -253,7 +253,7 @@ namespace Phonon
                     hr = w.graph->RenderFile(reinterpret_cast<const wchar_t *>(w.url.utf16()), 0);
                 }
                 if (hr != E_ABORT) {
-					emit asyncRenderFinished(w.id, hr, w.graph);
+                    emit asyncRenderFinished(w.id, hr, w.graph);
                 }
             } else if (w.task == Seek) {
                 //that's a seekrequest
@@ -269,7 +269,7 @@ namespace Phonon
                     }
                 }
                 emit asyncSeekingFinished(w.id, currentTime);
-                hr = E_ABORT; //to avoid emitting asyncRenderFinished 
+                hr = E_ABORT; //to avoid emitting asyncRenderFinished
             } else if (w.task == ChangeState) {
 
                 //remove useless decoders
@@ -330,16 +330,14 @@ namespace Phonon
             {
                 QMutexLocker locker(&m_mutex);
                 m_currentRender = Graph();
-			    m_currentRenderId = 0;
+                m_currentRenderId = 0;
             }
-
         }
 
-		void WorkerThread::abortCurrentRender(qint16 renderId)
-		{
+        void WorkerThread::abortCurrentRender(qint16 renderId)
+        {
             QMutexLocker locker(&m_mutex);
             bool found = false;
-            //we try to see if there is already an attempt to seek and we remove it
             for(int i = 0; !found && i < m_queue.size(); ++i) {
                 const Work &w = m_queue.at(i);
                 if (w.id == renderId) {
@@ -348,10 +346,10 @@ namespace Phonon
                 }
             }
 
-			if (m_currentRender && m_currentRenderId == renderId) {
-				m_currentRender->Abort();
-			}
-		}
+            if (m_currentRender && m_currentRenderId == renderId) {
+                m_currentRender->Abort();
+            }
+        }
 
         //tells the thread to stop processing
         void WorkerThread::signalStop()
@@ -389,13 +387,13 @@ namespace Phonon
         {
 
             for(int i = 0; i < FILTER_COUNT; ++i) {
-                m_graphs[i] = new MediaGraph(this, i);                
+                m_graphs[i] = new MediaGraph(this, i);
             }
 
-            connect(&m_thread, SIGNAL(stateReady(Graph, Phonon::State)), 
+            connect(&m_thread, SIGNAL(stateReady(Graph, Phonon::State)),
                                SLOT(slotStateReady(Graph, Phonon::State)));
 
-            connect(&m_thread, SIGNAL(eventReady(Graph, long, long)), 
+            connect(&m_thread, SIGNAL(eventReady(Graph, long, long)),
                                SLOT(handleEvents(Graph, long, long)));
 
             connect(&m_thread, SIGNAL(asyncRenderFinished(quint16, HRESULT, Graph)),
@@ -490,7 +488,7 @@ namespace Phonon
                     }
 
                     if (!m_aboutToFinishSent && remaining < PRELOAD_TIME - m_transitionTime  + TIMER_INTERVAL/2) {
-                        //let's take a 2 seconds time time to actually load the next file
+                        //let's take a 2 seconds time to actually load the next file
 #ifdef GRAPH_DEBUG
                         qDebug() << "DS9: emit aboutToFinish" << remaining << QTime::currentTime().toString();
 #endif
@@ -579,7 +577,7 @@ namespace Phonon
         {
 #ifndef QT_NO_PHONON_MEDIACONTROLLER
             //1st, check if there is more titles after
-            const qint64 ret = (m_currentTitle < _iface_availableTitles() - 1) ? 
+            const qint64 ret = (m_currentTitle < _iface_availableTitles() - 1) ?
                 titleAbsolutePosition(m_currentTitle+1) : currentGraph()->absoluteTotalTime();
 
             //this is the duration of the current title
@@ -592,7 +590,7 @@ namespace Phonon
         qint64 MediaObject::currentTime() const
         {
             //this handles inaccuracy when stopping on a title
-            return currentGraph()->absoluteCurrentTime() 
+            return currentGraph()->absoluteCurrentTime()
 #ifndef QT_NO_PHONON_MEDIACONTROLLER
                 - titleAbsolutePosition(m_currentTitle)
 #endif //QT_NO_PHONON_MEDIACONTROLLER
@@ -742,7 +740,7 @@ namespace Phonon
             m_oldHasVideo = currentGraph()->hasVideo();
             setState(Phonon::LoadingState);
             //After loading we go into stopped state
-            m_nextState = Phonon::StoppedState; 
+            m_nextState = Phonon::StoppedState;
             catchComError(currentGraph()->loadSource(source));
             emit currentSourceChanged(source);
         }
@@ -756,7 +754,7 @@ namespace Phonon
 
         void MediaObject::loadingFinished(MediaGraph *mg)
         {
-            if (mg == currentGraph()) { 
+            if (mg == currentGraph()) {
 #ifndef QT_NO_PHONON_MEDIACONTROLLER
                 //Title interface
                 m_currentTitle = 0;
@@ -813,7 +811,7 @@ namespace Phonon
 
         void MediaObject::seekingFinished(MediaGraph *mg)
         {
-            if (mg == currentGraph()) { 
+            if (mg == currentGraph()) {
 
                 updateTargetTick();
                 if (currentTime() < totalTime() - m_prefinishMark) {
@@ -888,7 +886,7 @@ namespace Phonon
 #ifndef QT_NO_PHONON_VIDEO
                 if (VideoWidget *video = qobject_cast<VideoWidget*>(sink)) {
                     m_videoWidgets += video;
-                } else 
+                } else
 #endif //QT_NO_PHONON_VIDEO
                     if (AudioOutput *audio = qobject_cast<AudioOutput*>(sink)) {
                     m_audioOutputs += audio;
@@ -907,7 +905,7 @@ namespace Phonon
 #ifndef QT_NO_PHONON_VIDEO
                 if (VideoWidget *video = qobject_cast<VideoWidget*>(sink)) {
                     m_videoWidgets.removeOne(video);
-                } else 
+                } else
 #endif //QT_NO_PHONON_VIDEO
                     if (AudioOutput *audio = qobject_cast<AudioOutput*>(sink)) {
                         m_audioOutputs.removeOne(audio);
@@ -989,7 +987,7 @@ namespace Phonon
                     emit stateChanged(state(), m_state);
                 }
                 break;
-            case EC_LENGTH_CHANGED: 
+            case EC_LENGTH_CHANGED:
                 if (graph == currentGraph()->graph()) {
                     emit totalTimeChanged( totalTime() );
                 }
diff --git a/src/3rdparty/phonon/ds9/qmeminputpin.cpp b/src/3rdparty/phonon/ds9/qmeminputpin.cpp
index 0af1bfde26..dca99dbc51 100644
--- a/src/3rdparty/phonon/ds9/qmeminputpin.cpp
+++ b/src/3rdparty/phonon/ds9/qmeminputpin.cpp
@@ -28,7 +28,7 @@ namespace Phonon
     namespace DS9
     {
 
-        QMemInputPin::QMemInputPin(QBaseFilter *parent, const QVector<AM_MEDIA_TYPE> &mt, bool transform) : 
+        QMemInputPin::QMemInputPin(QBaseFilter *parent, const QVector<AM_MEDIA_TYPE> &mt, bool transform) :
             QPin(parent, PINDIR_INPUT, mt), m_shouldDuplicateSamples(true), m_transform(transform)
         {
         }
@@ -203,7 +203,7 @@ namespace Phonon
 
             for (int i = 0; i < m_outputs.count(); ++i) {
                 QPin *current = m_outputs.at(i);
-                IMediaSample *outSample = m_shouldDuplicateSamples ? 
+                IMediaSample *outSample = m_shouldDuplicateSamples ?
                     duplicateSampleForOutput(sample, current->memoryAllocator())
                     : sample;
 
@@ -261,7 +261,7 @@ namespace Phonon
         }
 
         //addition
-        //this should be used by the filter to tell it's input pins to which output they should route the samples
+        //this should be used by the filter to tell its input pins to which output they should route the samples
 
         void QMemInputPin::addOutput(QPin *output)
         {
diff --git a/src/3rdparty/phonon/phonon/backendcapabilities.h b/src/3rdparty/phonon/phonon/backendcapabilities.h
index 65b2830056..36454a3da7 100644
--- a/src/3rdparty/phonon/phonon/backendcapabilities.h
+++ b/src/3rdparty/phonon/phonon/backendcapabilities.h
@@ -6,7 +6,7 @@
     License as published by the Free Software Foundation; either
     version 2.1 of the License, or (at your option) version 3, or any
     later version accepted by the membership of KDE e.V. (or its
-    successor approved by the membership of KDE e.V.), Trolltech ASA 
+    successor approved by the membership of KDE e.V.), Trolltech ASA
     (or its successors, if any) and the KDE Free Qt Foundation, which shall
     act as a proxy defined in Section 6 of version 3 of the license.
 
@@ -15,7 +15,7 @@
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Lesser General Public License for more details.
 
-    You should have received a copy of the GNU Lesser General Public 
+    You should have received a copy of the GNU Lesser General Public
     License along with this library.  If not, see <http://www.gnu.org/licenses/>.
 
 */
@@ -88,19 +88,18 @@ namespace BackendCapabilities
     };
 
     /**
-     * Use this function to get a QObject pointer to connect to the capabilitiesChanged signal.
+     * Use this function to get a QObject pointer to connect to one of the Notifier signals.
      *
      * \return a pointer to a QObject.
      *
-     * The capabilitiesChanged signal is emitted if the capabilities have changed. This can
-     * happen if the user has requested a backend change.
-     *
-     * To connect to this signal do the following:
+     * To connect to the signal do the following:
      * \code
      * QObject::connect(BackendCapabilities::notifier(), SIGNAL(capabilitiesChanged()), ...
      * \endcode
      *
      * \see Notifier::capabilitiesChanged()
+     * \see Notifier::availableAudioOutputDevicesChanged()
+     * \see Notifier::availableAudioCaptureDevicesChanged()
      */
     PHONON_EXPORT Notifier *notifier();
 
diff --git a/src/3rdparty/phonon/phonon/mediaobject.h b/src/3rdparty/phonon/phonon/mediaobject.h
index 5cbddbbefd..c56b6b5392 100644
--- a/src/3rdparty/phonon/phonon/mediaobject.h
+++ b/src/3rdparty/phonon/phonon/mediaobject.h
@@ -6,7 +6,7 @@
     License as published by the Free Software Foundation; either
     version 2.1 of the License, or (at your option) version 3, or any
     later version accepted by the membership of KDE e.V. (or its
-    successor approved by the membership of KDE e.V.), Trolltech ASA 
+    successor approved by the membership of KDE e.V.), Trolltech ASA
     (or its successors, if any) and the KDE Free Qt Foundation, which shall
     act as a proxy defined in Section 6 of version 3 of the license.
 
@@ -15,7 +15,7 @@
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Lesser General Public License for more details.
 
-    You should have received a copy of the GNU Lesser General Public 
+    You should have received a copy of the GNU Lesser General Public
     License along with this library.  If not, see <http://www.gnu.org/licenses/>.
 
 */
@@ -58,7 +58,7 @@ namespace Phonon
      * media->play();
      * \endcode
      *
-     * If you want to play more that one media file (one after another) you can
+     * If you want to play more than one media file (one after another) you can
      * either tell MediaObject about all those files
      * \code
      * media->setCurrentSource(":/sounds/startsound.ogg");
@@ -198,18 +198,18 @@ namespace Phonon
              * Check whether the current media may be seeked.
              *
              * \warning This information cannot be known immediately. It is best
-             * to also listen to the hasVideoChanged signal.
+             * to also listen to the seekableChanged signal.
              *
              * \code
-             *   connect(media, SIGNAL(hasVideoChanged(bool)), hasVideoChanged(bool));
+             *   connect(media, SIGNAL(seekableChanged(bool)), seekableChanged(bool));
              *   media->setCurrentSource("somevideo.avi");
-             *   media->hasVideo(); // returns false;
+             *   media->isSeekable(); // returns false;
              * }
              *
-             * void hasVideoChanged(bool b)
+             * void seekableChanged(bool b)
              * {
              *   // b == true
-             *   media->hasVideo(); // returns true;
+             *   media->isSeekable(); // returns true;
              * }
              * \endcode
              *
@@ -301,7 +301,7 @@ namespace Phonon
             void setCurrentSource(const MediaSource &source);
 
             /**
-             * Returns the queued media sources. This does list does not include
+             * Returns the queued media sources. This list does not include
              * the current source (returned by currentSource).
              */
             QList<MediaSource> queue() const;
@@ -456,8 +456,6 @@ namespace Phonon
         Q_SIGNALS:
             /**
              * Emitted when the state of the MediaObject has changed.
-             * In case you're not interested in the old state you can also
-             * connect to a slot that only has one State argument.
              *
              * @param newstate The state the Player is in now.
              * @param oldstate The state the Player was in before.
@@ -587,7 +585,7 @@ namespace Phonon
             /**
              * This signal is emitted as soon as the total time of the media file is
              * known or has changed. For most non-local media data the total
-             * time of the media can only be known after some time. At that time the
+             * time of the media can only be known after some time. Initially the
              * totalTime function can not return useful information. You have
              * to wait for this signal to know the real total time.
              *