Overhaul documentation for Qt 6 Release, Second Block

Remove Audio QML type
Add links to technical definitions
Spelling and grammer check
Changes to adhere to Qt Doc guide
Integrated change to qt 6 page (porting guide)
Break out Audio QML type removal into it's own line in changes table
Reflow docs text within 100 characters

Task-number: QTBUG-94646 QTBUG-94906
Change-Id: I65ca7083e68d0bf534fd4faecfa7c501bab83b24
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Lars Knoll <lars.knoll@qt.io>

1 files changed, 38 insertions, 33 deletions

diff --git a/src/multimedia/qmediaformat.cpp b/src/multimedia/qmediaformat.cpp
index 4cd66143a..a25d1f33f 100644
--- a/src/multimedia/qmediaformat.cpp
+++ b/src/multimedia/qmediaformat.cpp
@@ -43,7 +43,18 @@
 #include <QtCore/qmimedatabase.h>
 
 QT_BEGIN_NAMESPACE
+/*!
+    \class QMediaFormat
+    \ingroup multimedia
+    \inmodule QtMultimedia
+    \brief Describes an encoding format for a multimedia file or stream.
+
+    QMediaFormat describes an encoding format for a multimedia file or stream.
 
+    You can check whether a certain media format can be used for encoding
+    or decoding using QMediaDecoderInfo or QMediaRecorderInfo.
+    \since 6.2
+*/
 namespace {
 
 const char *mimeTypeForFormat[QMediaFormat::LastFileFormat + 2] =
@@ -151,20 +162,10 @@ QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QMediaFormatPrivate);
     \omitvalue LastVideoCodec
 */
 
-/*! \class QMediaFormat
-    \inmodule QtMultimedia
-    \since 6.2
-
-    Describes an encoding format for a multimedia file or stream.
-
-    You can check whether a certain QMediaFormat can be used for encoding
-    or decoding using QMediaDecoderInfo or QMediaRecorderInfo.
-*/
-
 // these are non inline to make a possible future addition of a d pointer binary compatible
 
 /*!
-    Constucts a QMediaFormat object for \a format.
+    Constructs a QMediaFormat object for \a format.
 */
 QMediaFormat::QMediaFormat(FileFormat format)
     : fmt(format)
@@ -251,17 +252,17 @@ QMediaFormat &QMediaFormat::operator=(const QMediaFormat &other) noexcept = defa
     depending on \a mode.
 
     \sa QMediaDecoderInfo
- */
+*/
 bool QMediaFormat::isSupported(ConversionMode mode) const
 {
     return QPlatformMediaIntegration::instance()->formatInfo()->isSupported(*this, mode);
 }
 
 /*!
-    Returns the mimetype for the file format used in this media format.
+    Returns the \l{MIME type} for the file format used in this media format.
 
     \sa format(), setFormat()
- */
+*/
 QMimeType QMediaFormat::mimeType() const
 {
     return QMimeDatabase().mimeTypeForName(QString::fromLatin1(mimeTypeForFormat[fmt + 1]));
@@ -276,13 +277,12 @@ static QPlatformMediaFormatInfo *formatInfo()
 }
 
 /*!
-    Returns a list of container formats that are supported for \a mode.
+    The function returns a list of file formats for the chosen audio and video
+    codec.
 
-    The list is constrained by the chosen audio and video codec and will only match file
-    formats that can be created with those codecs.
-
-    To get all supported file formats, run this query on a default constructed QMediaFormat.
- */
+    To get all supported file formats, run this query on a default constructed
+    QMediaFormat.
+*/
 QList<QMediaFormat::FileFormat> QMediaFormat::supportedFileFormats(QMediaFormat::ConversionMode m)
 {
     auto *fi = formatInfo();
@@ -290,13 +290,12 @@ QList<QMediaFormat::FileFormat> QMediaFormat::supportedFileFormats(QMediaFormat:
 }
 
 /*!
-    Returns a list of video codecs that are supported for \a mode.
-
-    The list is constrained by the chosen file format and audio codec and will only return
-    the video codecs that can be used with those settings.
+    The function returns a list of audio codecs for the chosen file format and
+    video codec.
 
-    To get all supported video codecs, run this query on a default constructed QMediaFormat.
- */
+    To get all supported video codecs, run this query on a default constructed
+    QMediaFormat.
+*/
 QList<QMediaFormat::VideoCodec> QMediaFormat::supportedVideoCodecs(QMediaFormat::ConversionMode m)
 {
     auto *fi = formatInfo();
@@ -304,13 +303,12 @@ QList<QMediaFormat::VideoCodec> QMediaFormat::supportedVideoCodecs(QMediaFormat:
 }
 
 /*!
-    Returns a list of audio codecs that are supported for \a mode.
-
-    The list is constrained by the chosen file format and video codec and will only return
-    the audio codecs that can be used with those settings.
+    The function returns a list of audio codecs for the chosen file format and
+    video codec.
 
-    To get all supported audio codecs, run this query on a default constructed QMediaFormat.
- */
+    To get all supported audio codecs, run this query on a default constructed
+    QMediaFormat.
+*/
 QList<QMediaFormat::AudioCodec> QMediaFormat::supportedAudioCodecs(QMediaFormat::ConversionMode m)
 {
     auto *fi = formatInfo();
@@ -451,7 +449,14 @@ bool QMediaFormat::operator==(const QMediaFormat &other) const
     This method tries to find the best possible match for unspecified settings.
     Settings that are not supported by the recorder will be modified to the closest
     match that is supported.
- */
+
+    When resolving, priority is given in the following order:
+    \list 1
+    \li File format
+    \li Video codec
+    \li Audio codec
+    \endlist
+*/
 void QMediaFormat::resolveForEncoding(ResolveFlags flags)
 {
     const bool requiresVideo = (flags & ResolveFlags::RequiresVideo) != 0;