Doc: Fix various documentation issues for Qt Core

Task-number: QTBUG-86295 Change-Id: I3bf7d4b1533d4fc81114d353b19beaf4ea9b93b2 Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
2020-10-29 18:11:22 +01:00 · 2020-10-29 18:11:22 +01:00 · 739e7dd191
commit 739e7dd191
parent d16ac88cb0
13 changed files with 42 additions and 36 deletions
--- a/src/corelib/kernel/qdeadlinetimer.cpp
+++ b/src/corelib/kernel/qdeadlinetimer.cpp
@ -873,7 +873,7 @@ QDeadlineTimer QDeadlineTimer::addNSecs(QDeadlineTimer dt, qint64 nsecs) noexcep
 */

 /*!
-    \fn bool QDeadlineTimer::operator==(QDeadlineTimer d1, QDeadlineTimer::QDeadlineTimer d2)
+    \fn bool QDeadlineTimer::operator==(QDeadlineTimer d1, QDeadlineTimer d2)

    Returns true if the deadline on \a d1 and the deadline in \a d2 are the
    same, false otherwise. The timer type used to create the two deadlines is
@ -951,8 +951,7 @@ QDeadlineTimer QDeadlineTimer::addNSecs(QDeadlineTimer dt, qint64 nsecs) noexcep
 */

 /*!
-    \fn QDeadlineTimer operator+(QDeadlineTimer dt, qint64 msecs)
-    \relates QDeadlineTimer
+    \fn QDeadlineTimer QDeadlineTimer::operator+(QDeadlineTimer dt, qint64 msecs)

    Returns a QDeadlineTimer object whose deadline is \a msecs later than the
    deadline stored in \a dt. If \a dt is set to never expire, this function
--- a/src/corelib/kernel/qmetaobject.cpp
+++ b/src/corelib/kernel/qmetaobject.cpp
@ -2943,7 +2943,7 @@ const char *QMetaProperty::typeName() const
    Returns this property's type. The return value is one
    of the values of the QVariant::Type enumeration.

-    \sa metaType().id(), typeName(), name(), metaType()
+    \sa typeName(), name(), metaType()
 */

 /*! \fn int QMetaProperty::userType() const
@ -3248,7 +3248,7 @@ bool QMetaProperty::reset(QObject *object) const
    If the property doesn't support bindings, the returned interface will be
    invalid.

-    \sa QUntypedBindable, QProperty, isBindable()
+    \sa QObjectBindableProperty, QProperty, isBindable()
 */
 QUntypedBindable QMetaProperty::bindable(QObject *object) const
 {
--- a/src/corelib/kernel/qmetatype.cpp
+++ b/src/corelib/kernel/qmetatype.cpp
@ -409,7 +409,7 @@ Q_GLOBAL_STATIC(QMetaTypeCustomRegistry, customTypeRegistry)

    \value NeedsConstruction This type has non-trivial constructors. If the flag is not set instances can be safely initialized with memset to 0.
    \value NeedsDestruction This type has a non-trivial destructor. If the flag is not set calls to the destructor are not necessary before discarding objects.
-    \value ReloctableType An instance of a type having this attribute can be safely moved to a different memory location using memcpy.
+    \value RelocatableType An instance of a type having this attribute can be safely moved to a different memory location using memcpy.
    \omitvalue MovableType
    \omitvalue SharedPointerToQObject
    \value IsEnumeration This type is an enumeration.
@ -2580,7 +2580,7 @@ Q_CORE_EXPORT int qMetaTypeTypeInternal(const char *typeName)
 }

 /*!
-    \fn int QMetaType::type(const QByteArray &typeName)
+    \fn int QMetaType::type(const QT_PREPEND_NAMESPACE(QByteArray) &typeName)

    \since 5.5
    \overload
--- a/src/corelib/kernel/qmimedata.cpp
+++ b/src/corelib/kernel/qmimedata.cpp
@ -320,7 +320,7 @@ QT_WARNING_POP
    QMacPasteboardMime maps MIME to Mac flavors.

    \sa QClipboard, QDragEnterEvent, QDragMoveEvent, QDropEvent, QDrag,
-        QMacPasteboardMime, {Drag and Drop}
+        {Drag and Drop}
 */

 /*!
--- a/src/corelib/kernel/qobject.cpp
+++ b/src/corelib/kernel/qobject.cpp
@ -4217,8 +4217,8 @@ QDebug operator<<(QDebug dbg, const QObject *o)
    \relates QObject

    This macro associates extra information to the class, which is available
-    using QObject::metaObject(). Qt makes only limited use of this feature, in
-    the \l{Active Qt}, \l{Qt D-Bus} and \l{Qt QML module}{Qt QML}.
+    using QObject::metaObject(). Qt makes only limited use of this feature in
+    \l{Qt D-Bus} and \l{Qt QML module}{Qt QML}.

    The extra information takes the form of a \a Name string and a \a Value
    literal string.
@ -4228,7 +4228,6 @@ QDebug operator<<(QDebug dbg, const QObject *o)
    \snippet code/src_corelib_kernel_qobject.cpp 35

    \sa QMetaObject::classInfo()
-    \sa QAxFactory
    \sa {Using Qt D-Bus Adaptors}
    \sa {Extending QML}
 */
--- a/src/corelib/kernel/qobjectdefs.h
+++ b/src/corelib/kernel/qobjectdefs.h
@ -459,9 +459,9 @@ public:
    operator RestrictedBool() const { return d_ptr && isConnected_helper() ? &Connection::d_ptr : nullptr; }
 #endif

-    Connection(Connection &&o) noexcept : d_ptr(qExchange(o.d_ptr, nullptr)) {}
+    Connection(Connection &&other) noexcept : d_ptr(qExchange(other.d_ptr, nullptr)) {}
    QT_MOVE_ASSIGNMENT_OPERATOR_IMPL_VIA_PURE_SWAP(Connection)
-    void swap(Connection &o) noexcept { qSwap(d_ptr, o.d_ptr); }
+    void swap(Connection &other) noexcept { qSwap(d_ptr, other.d_ptr); }
 };

 inline void swap(QMetaObject::Connection &lhs, QMetaObject::Connection &rhs) noexcept
--- a/src/corelib/kernel/qproperty.cpp
+++ b/src/corelib/kernel/qproperty.cpp
@ -1038,7 +1038,7 @@ QString QPropertyBindingError::description() const
  expression and returns the previously associated binding. The first time the
  property value is read, the binding is evaluated. Whenever a dependency of the
  binding changes, the binding will be re-evaluated the next time the value of
-  this property is read. When the property value changes \a owner is notified
+  this property is read. When the property value changes, the owner is notified
  via the Callback function.
 */

@ -1051,7 +1051,7 @@ QString QPropertyBindingError::description() const
  is read, the binding is evaluated by invoking the call operator () of \a f.
  Whenever a dependency of the binding changes, the binding will be re-evaluated
  the next time the value of this property is read. When the property value
-  changes \a owner is notified via the Callback function.
+  changes, the owner is notified via the Callback function.
 */

 /*!
--- a/src/corelib/plugin/qpluginloader.cpp
+++ b/src/corelib/plugin/qpluginloader.cpp
@ -464,9 +464,9 @@ QList<QStaticPlugin> QPluginLoader::staticPlugins()
 */

 /*!
-    \fn QObject *QStaticPlugin::instance()
+    \variable QStaticPlugin::instance

-    Returns the plugin instance.
+    Holds the plugin instance.

    \sa QPluginLoader::staticInstances()
 */
--- a/src/corelib/text/qbytearray.cpp
+++ b/src/corelib/text/qbytearray.cpp
@ -532,7 +532,7 @@ quint16 qChecksum(QByteArrayView data, Qt::ChecksumType standard)
    The default value is -1, which specifies zlib's default
    compression.

-    \sa qUncompress()
+    \sa qUncompress(const QByteArray &data)
 */

 /*! \relates QByteArray
--- a/src/corelib/text/qlocale.qdoc
+++ b/src/corelib/text/qlocale.qdoc
@ -314,6 +314,7 @@
    \value Nepali
    \value Newari Since Qt 5.7
    \value Ngiemboon
+    \value NigerianPidgin Since Qt 6.0
    \value Ngomba
    \value Nko Since Qt 5.5
    \value NorthernLuri Since Qt 5.7
--- a/src/corelib/tools/qcontiguouscache.cpp
+++ b/src/corelib/tools/qcontiguouscache.cpp
@ -119,7 +119,7 @@ void QContiguousCacheData::freeData(QContiguousCacheData *data)
    See the \l{Contiguous Cache Example}{Contiguous Cache} example.
 */

-/*! \fn template<typename T> QContiguousCache<T>::QContiguousCache(int capacity)
+/*! \fn template<typename T> QContiguousCache<T>::QContiguousCache(qsizetype capacity)

    Constructs a cache with the given \a capacity.

@ -224,7 +224,7 @@ void QContiguousCacheData::freeData(QContiguousCacheData *data)
    \sa operator==()
 */

-/*! \fn template<typename T> int QContiguousCache<T>::capacity() const
+/*! \fn template<typename T> qsizetype QContiguousCache<T>::capacity() const

    Returns the number of items the cache can store before it is full.
    When a cache contains a number of items equal to its capacity, adding new
@ -233,12 +233,12 @@ void QContiguousCacheData::freeData(QContiguousCacheData *data)
    \sa setCapacity(), size()
 */

-/*! \fn template<typename T> int QContiguousCache<T>::count() const
+/*! \fn template<typename T> qsizetype QContiguousCache<T>::count() const

    Same as size().
 */

-/*! \fn template<typename T> int QContiguousCache<T>::size() const
+/*! \fn template<typename T> qsizetype QContiguousCache<T>::size() const

    Returns the number of items contained within the cache.

@ -260,7 +260,7 @@ void QContiguousCacheData::freeData(QContiguousCacheData *data)
    \sa size(), capacity()
 */

-/*! \fn template<typename T> int QContiguousCache<T>::available() const
+/*! \fn template<typename T> qsizetype QContiguousCache<T>::available() const

    Returns the number of items that can be added to the cache before it becomes full.

@ -272,7 +272,7 @@ void QContiguousCacheData::freeData(QContiguousCacheData *data)
    Removes all items from the cache.  The capacity is unchanged.
 */

-/*! \fn template<typename T> void QContiguousCache<T>::setCapacity(int size)
+/*! \fn template<typename T> void QContiguousCache<T>::setCapacity(qsizetype size)

    Sets the capacity of the cache to the given \a size.  A cache can hold a
    number of items equal to its capacity.  When inserting, appending or prepending
@ -285,7 +285,7 @@ void QContiguousCacheData::freeData(QContiguousCacheData *data)
    \sa capacity(), isFull()
 */

-/*! \fn template<typename T> const T &QContiguousCache<T>::at(int i) const
+/*! \fn template<typename T> const T &QContiguousCache<T>::at(qsizetype i) const

    Returns the item at index position \a i in the cache.  \a i must
    be a valid index position in the cache (i.e, firstIndex() <= \a i <= lastIndex()).
@ -299,7 +299,7 @@ void QContiguousCacheData::freeData(QContiguousCacheData *data)
    \sa firstIndex(), lastIndex(), insert(), operator[]()
 */

-/*! \fn template<typename T> T &QContiguousCache<T>::operator[](int i)
+/*! \fn template<typename T> T &QContiguousCache<T>::operator[](qsizetype i)

    Returns the item at index position \a i as a modifiable reference. If
    the cache does not contain an item at the given index position \a i
@ -314,7 +314,7 @@ void QContiguousCacheData::freeData(QContiguousCacheData *data)
    \sa insert(), at()
 */

-/*! \fn template<typename T> const T &QContiguousCache<T>::operator[](int i) const
+/*! \fn template<typename T> const T &QContiguousCache<T>::operator[](qsizetype i) const

    \overload

@ -337,7 +337,7 @@ void QContiguousCacheData::freeData(QContiguousCacheData *data)
    \sa append(), insert(), isFull()
 */

-/*! \fn template<typename T> void QContiguousCache<T>::insert(int i, const T &value)
+/*! \fn template<typename T> void QContiguousCache<T>::insert(qsizetype i, const T &value)

    Inserts the \a value at the index position \a i.  If the cache already contains
    an item at \a i then that value is replaced.  If \a i is either one more than
@ -357,14 +357,14 @@ void QContiguousCacheData::freeData(QContiguousCacheData *data)
    \sa prepend(), append(), isFull(), firstIndex(), lastIndex()
 */

-/*! \fn template<typename T> bool QContiguousCache<T>::containsIndex(int i) const
+/*! \fn template<typename T> bool QContiguousCache<T>::containsIndex(qsizetype i) const

    Returns \c true if the cache's index range includes the given index \a i.

    \sa firstIndex(), lastIndex()
 */

-/*! \fn template<typename T> int QContiguousCache<T>::firstIndex() const
+/*! \fn template<typename T> qsizetype QContiguousCache<T>::firstIndex() const

    Returns the first valid index in the cache.  The index will be invalid if the
    cache is empty.
@ -372,7 +372,7 @@ void QContiguousCacheData::freeData(QContiguousCacheData *data)
    \sa capacity(), size(), lastIndex()
 */

-/*! \fn template<typename T> int QContiguousCache<T>::lastIndex() const
+/*! \fn template<typename T> qsizetype QContiguousCache<T>::lastIndex() const

    Returns the last valid index in the cache.  The index will be invalid if the cache is empty.

--- a/src/corelib/tools/qiterator.qdoc
+++ b/src/corelib/tools/qiterator.qdoc
@ -785,7 +785,7 @@
    continue iterating over the original map, ignoring the modified
    copy.

-    \sa QMutableMultiMapIterator, QMultiMapIterator::const_iterator
+    \sa QMutableMultiMapIterator
 */

 /*!
@ -1131,7 +1131,7 @@
    Calling this function on an iterator located at the back of the
    container leads to undefined results.

-    \sa hasNext(), peekNext(), previous()
+    \sa hasNext(), {QMapIterator::}{peekNext()}, previous()
 */

 /*! \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::next()
@ -1177,7 +1177,7 @@
 */

 /*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::peekNext() const
-    \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekNext()
+    \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekNext() const

    Returns the next item without moving the iterator.

@ -1191,7 +1191,7 @@
 */

 /*! \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekNext() const
-    \fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::peekNext()
+    \fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::peekNext() const

    Returns a reference to the next item without moving the iterator.

@ -1274,7 +1274,7 @@
    Calling this function on an iterator located at the front of the
    container leads to undefined results.

-    \sa hasPrevious(), previous(), peekNext()
+    \sa hasPrevious(), previous(), {QMapIterator::}{peekNext()}
 */

 /*! \fn template <class Key, class T> const T &QMapIterator<Key, T>::value() const
--- a/src/corelib/tools/qpair.qdoc
+++ b/src/corelib/tools/qpair.qdoc
@ -40,6 +40,13 @@
    \sa {Container Classes}
 */

+/*!
+    \typealias QPair
+    \relates QPair
+    \since 6.0
+    Typedef for std::pair\<T1, T2\>.
+*/
+
 /*!
    \fn template <class T1, class T2> QPair<T1, T2> qMakePair(T1 &&value1, T2 &&value2)
    \obsolete