Fix documentation warnings

Declare hidden friends like qdoc expects them, and other signature fixes
Document function parameters
Remove documentation for removed APIs.

Change-Id: I44c1caeed0d40be04612129d074acc30b75f5259
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>

src/corelib/kernel/qpointer.cpp

@@ -201,8 +201,7 @@
 */
 
 /*!
-    \fn template <class T> bool operator==(const T *o, const QPointer<T> &p)
+    \fn template <typename T, typename X> bool QPointer<T>::operator==(X *o, const QPointer<T> &p)
-    \relates QPointer
 
     Equality operator. Returns \c true if \a o and the guarded
     pointer \a p are pointing to the same object, otherwise
@@ -210,8 +209,7 @@
 
 */
 /*!
-    \fn template <class T> bool operator==(const QPointer<T> &p, const T *o)
+    \fn template <typename T, typename X> bool QPointer<T>::operator==(const QPointer<T> &p, X *o)
-    \relates QPointer
 
     Equality operator. Returns \c true if \a o and the guarded
     pointer \a p are pointing to the same object, otherwise
@@ -219,74 +217,64 @@
 
 */
 /*!
-    \fn template <class T> bool operator==(T *o, const QPointer<T> &p)
+    \fn template <typename T, typename X> bool QPointer<T>::operator==(const QPointer<T> &p1, const QPointer<X> &p2)
-    \relates QPointer
-
-    Equality operator. Returns \c true if \a o and the guarded
-    pointer \a p are pointing to the same object, otherwise
-    returns \c false.
-
-*/
-/*!
-    \fn template <class T> bool operator==(const QPointer<T> &p, T *o)
-    \relates QPointer
-
-    Equality operator. Returns \c true if \a o and the guarded
-    pointer \a p are pointing to the same object, otherwise
-    returns \c false.
-
-*/
-/*!
-    \fn template <class T> bool operator==(const QPointer<T> &p1, const QPointer<T> &p2)
-    \relates QPointer
 
     Equality operator. Returns \c true if the guarded pointers \a p1 and \a p2
     are pointing to the same object, otherwise
     returns \c false.
 
 */
+/*!
+    \fn template <typename T> bool QPointer<T>::operator==(std::nullptr_t, const QPointer<T> &rhs)
 
+    Equality operator. Returns \c true if the pointer guarded by \a rhs
+    is \nullptr, otherwise
+    returns \c false.
+*/
+/*!
+    \fn template <typename T> bool QPointer<T>::operator==(const QPointer<T> &lhs, std::nullptr_t)
+
+    Equality operator. Returns \c true if the pointer guarded by \a lhs
+    is \nullptr, otherwise
+    returns \c false.
+*/
 
 /*!
-    \fn template <class T> bool operator!=(const T *o, const QPointer<T> &p)
+    \fn template <typename T, typename X> bool QPointer<T>::operator!=(const QPointer<T> &p, X *o)
-    \relates QPointer
 
     Inequality operator. Returns \c true if \a o and the guarded
     pointer \a p are not pointing to the same object, otherwise
     returns \c false.
 */
 /*!
-    \fn template <class T> bool operator!=(const QPointer<T> &p, const T *o)
+    \fn template <typename T, typename X> bool QPointer<T>::operator!=(X *o, const QPointer<T> &p)
-    \relates QPointer
 
     Inequality operator. Returns \c true if \a o and the guarded
     pointer \a p are not pointing to the same object, otherwise
     returns \c false.
 */
 /*!
-    \fn template <class T> bool operator!=(T *o, const QPointer<T> &p)
+    \fn template <typename T, typename X> bool QPointer<T>::operator!=(const QPointer<T> &p1, const QPointer<X> &p2)
-    \relates QPointer
-
-    Inequality operator. Returns \c true if \a o and the guarded
-    pointer \a p are not pointing to the same object, otherwise
-    returns \c false.
-*/
-/*!
-    \fn template <class T> bool operator!=(const QPointer<T> &p, T *o)
-    \relates QPointer
-
-    Inequality operator. Returns \c true if \a o and the guarded
-    pointer \a p are not pointing to the same object, otherwise
-    returns \c false.
-*/
-/*!
-    \fn template <class T> bool operator!=(const QPointer<T> &p1, const QPointer<T> &p2)
-    \relates QPointer
 
     Inequality operator. Returns \c true if  the guarded pointers \a p1 and
     \a p2 are not pointing to the same object, otherwise
     returns \c false.
 */
+/*!
+    \fn template <typename T> bool QPointer<T>::operator!=(std::nullptr_t, const QPointer<T> &rhs)
+
+    Inequality operator. Returns \c true if the pointer guarded by \a rhs is
+    a valid (ie not \nullptr) pointer, otherwise
+    returns \c false.
+*/
+/*!
+    \fn template <typename T> bool QPointer<T>::operator!=(const QPointer<T> &lhs, std::nullptr_t)
+
+    Inequality operator. Returns \c true if the pointer guarded by \a lhs is
+    a valid (ie not \nullptr) pointer, otherwise
+    returns \c false.
+*/
+
 /*!
     \fn template <typename T> QPointer<T> qPointerFromVariant(const QVariant &variant)
 

src/corelib/tools/qtaggedpointer.qdoc

@@ -153,7 +153,7 @@
 */
 
 /*!
-    \fn template <typename T, typename Tag> Tag QTaggedPointer<T, Tag>::pointer() const noexcept
+    \fn template <typename T, typename Tag> T *QTaggedPointer<T, Tag>::data() const noexcept
 
     Returns the pointer stored in the tagged pointer.
 */

src/corelib/tools/qversionnumber.cpp

@@ -578,7 +578,7 @@ size_t qHash(const QVersionNumber &key, size_t seed)
     \fn template<typename Integer> static bool QTypeRevision::isValidSegment(Integer segment)
 
     Returns true if the given number can be used as either major or minor
-    version in a QTypeRevision. Valid segments need to be \c {>= 0} and \c {< 255}.
+    version in a QTypeRevision. The valid range for \a segment is \c {>= 0} and \c {< 255}.
 */
 
 /*!

src/gui/kernel/qcursor.cpp

@@ -480,8 +480,7 @@ QCursor::QCursor(Qt::CursorShape shape)
 }
 
 /*!
-    \fn bool operator==(const QCursor &lhs, const QCursor &rhs)
+    \fn bool QCursor::operator==(const QCursor &lhs, const QCursor &rhs)
-    \relates QCursor
     \since 5.10
 
     Equality operator. Returns \c true if \a lhs and \a rhs
@@ -519,8 +518,7 @@ bool operator==(const QCursor &lhs, const QCursor &rhs) noexcept
 }
 
 /*!
-    \fn bool operator!=(const QCursor &lhs, const QCursor &rhs)
+    \fn bool QCursor::operator!=(const QCursor &lhs, const QCursor &rhs)
-    \relates QCursor
     \since 5.10
 
     Inequality operator. Returns the equivalent of !(\a lhs == \a rhs).

src/gui/kernel/qevent.cpp

@@ -274,7 +274,7 @@ QEventPoint &QEventPoint::operator=(const QEventPoint &other)
 */
 
 /*!
-    \fn QEventPoint &QEventPoint QEventPoint::operator=(QEventPoint &&other) noexcept
+    \fn QEventPoint &QEventPoint::operator=(QEventPoint &&other) noexcept
 
     Move-assigns \a other to this event point instance.
 */

src/gui/kernel/qpalette.cpp

@@ -157,13 +157,6 @@ static void qt_palette_from_color(QPalette &pal, const QColor &button)
     \sa brush(), setColor(), ColorRole
 */
 
-/*!
-    \fn const QBrush & QPalette::foreground() const
-    \obsolete
-
-    Use windowText() instead.
-*/
-
 /*!
     \fn const QBrush & QPalette::windowText() const
 
@@ -279,13 +272,6 @@ static void qt_palette_from_color(QPalette &pal, const QColor &button)
     \sa ColorRole, brush()
 */
 
-/*!
-    \fn const QBrush & QPalette::background() const
-    \obsolete
-
-    Use window() instead.
-*/
-
 /*!
     \fn const QBrush & QPalette::window() const
 
@@ -451,12 +437,8 @@ static void qt_palette_from_color(QPalette &pal, const QColor &button)
 
     \value Window  A general background color.
 
-    \value Background  This value is obsolete. Use Window instead.
-
     \value WindowText  A general foreground color.
 
-    \value Foreground  This value is obsolete. Use WindowText instead.
-
     \value Base  Used mostly as the background color for text entry widgets,
                  but can also be used for other painting - such as the
                  background of combobox drop down lists and toolbar handles.

src/gui/painting/qcolorspace.cpp

@@ -691,6 +691,7 @@ bool QColorSpace::isValid() const noexcept
 }
 
 /*!
+    \fn bool QColorSpace::operator==(const QColorSpace &colorSpace1, const QColorSpace &colorSpace2)
     \relates QColorSpace
     Returns \c true if colorspace \a colorSpace1 is equal to colorspace \a colorSpace2;
     otherwise returns \c false
@@ -742,8 +743,7 @@ bool operator==(const QColorSpace &colorSpace1, const QColorSpace &colorSpace2)
 }
 
 /*!
-    \fn bool operator!=(const QColorSpace &colorSpace1, const QColorSpace &colorSpace2)
+    \fn bool QColorSpace::operator!=(const QColorSpace &colorSpace1, const QColorSpace &colorSpace2)
-    \relates QColorSpace
 
     Returns \c true if colorspace \a colorSpace1 is not equal to colorspace \a colorSpace2;
     otherwise returns \c false

src/gui/text/qtextlayout.cpp

@@ -93,15 +93,13 @@ QT_BEGIN_NAMESPACE
     Specifies the format to apply.
 */
 
-/*! \fn bool operator==(const QTextLayout::FormatRange &lhs, const QTextLayout::FormatRange &rhs)
+/*! \fn bool QTextLayout::FormatRange::operator==(const QTextLayout::FormatRange &lhs, const QTextLayout::FormatRange &rhs)
-  \relates QTextLayout::FormatRange
 
   Returns true if the \c {start}, \c {length}, and \c {format} fields
   in \a lhs and \a rhs contain the same values respectively.
  */
 
-/*! \fn bool operator!=(const QTextLayout::FormatRange &lhs, const QTextLayout::FormatRange &rhs)
+/*! \fn bool QTextLayout::FormatRange::operator!=(const QTextLayout::FormatRange &lhs, const QTextLayout::FormatRange &rhs)
-  \relates QTextLayout::FormatRange
 
   Returns true if any of the \c {start}, \c {length}, or \c {format} fields
   in \a lhs and \a rhs contain different values respectively.