Fix some qdoc warnings in 5.14

Mark QCalendarBackend as internal since it is in a private header
and fix some issues in the QCalendar related classes.

src/corelib/time/qcalendar.cpp:201: (qdoc) warning: clang found diagnostics parsing \fn int QCalendarBackend::daysInMonth(int month, int year) const
    error: incomplete type 'QCalendarBackend' named in nested name specifier
(repeats)
src/corelib/time/qdatetime.cpp:1426: (qdoc) warning: Unknown command '\override' (repeats)
src/corelib/time/qcalendar.cpp:642: (qdoc) warning: Undocumented enum item 'Last' in QCalendar::System
src/corelib/time/qcalendar.cpp:642: (qdoc) warning: Undocumented enum item 'User' in QCalendar::System
src/corelib/time/qcalendar.cpp:744: (qdoc) warning: Undocumented parameter 'year' in QCalendar::isLeapYear()
src/corelib/time/qcalendar.cpp:923: (qdoc) warning: Can't link to 'dateTimeString()' (repeats)
src/corelib/time/qcalendar.cpp:893: (qdoc) warning: No such parameter 'year' in QCalendar::partsFromDate()
src/corelib/time/qcalendar.cpp:893: (qdoc) warning: No such parameter 'month' in QCalendar::partsFromDate()
src/corelib/time/qcalendar.cpp:893: (qdoc) warning: No such parameter 'day' in QCalendar::partsFromDate()
src/corelib/time/qdatetime.cpp:1425: (qdoc) warning: Undocumented parameter 'nmonths' in QDate::addMonths()
src/corelib/time/qdatetime.cpp:1467: (qdoc) warning: Undocumented parameter 'nyears' in QDate::addYears()
src/corelib/statemachine/qstatemachine.cpp:2522: (qdoc) warning: Undocumented enum item 'StateMachineChildModeSetToParallelError' in QStateMachine::Error
src/corelib/kernel/qtimer.cpp:602: (qdoc) warning: Undocumented parameter 'connectionType' in QTimer::callOnTimeout()
src/corelib/time/qcalendar.cpp:159: (qdoc) warning: Undocumented parameter 'name' in QCalendarBackend::QCalendarBackend()
src/corelib/time/qcalendar.cpp:159: (qdoc) warning: Undocumented parameter 'id' in QCalendarBackend::QCalendarBackend()
src/corelib/time/qcalendar.cpp:529: (qdoc) warning: Can't link to 'registerCalendar()'
src/corelib/time/qcalendar.cpp:529: (qdoc) warning: Can't link to 'fromName()'
src/corelib/time/qcalendar.cpp:178: (qdoc) warning: Can't link to 'QCalendar::fromEnum()'
src/corelib/time/qcalendar.cpp:405: (qdoc) warning: Undocumented parameter 'jd' in QCalendarBackend::dayOfWeek()
src/corelib/time/qcalendar.cpp:405: (qdoc) warning: Can't link to 'weekDayName()'
src/corelib/time/qcalendar.cpp:405: (qdoc) warning: Can't link to 'standaloneWeekDayName()'
src/corelib/time/qcalendar.cpp:268: (qdoc) warning: Can't link to 'daysInMonth()'
src/corelib/time/qcalendar.cpp:268: (qdoc) warning: Can't link to 'isLeapYear()'
src/corelib/time/qcalendar.cpp:295: (qdoc) warning: Can't link to 'daysInMonth()'
src/corelib/time/qcalendar.cpp:313: (qdoc) warning: Can't link to 'isLuniSolar()'
src/corelib/time/qcalendar.cpp:313: (qdoc) warning: Can't link to 'isSolar()'
src/corelib/time/qcalendar.cpp:313: (qdoc) warning: Can't link to 'isLunar()'
src/corelib/time/qcalendar.cpp:340: (qdoc) warning: Can't link to 'daysInMonth()'
src/corelib/time/qcalendar.cpp:357: (qdoc) warning: Can't link to 'daysInMonth()'
src/corelib/time/qcalendar.cpp:544: (qdoc) warning: Can't link to 'fromName()'

Change-Id: Ia2fabefb917f8e4cfa361044d9b754717276f4aa
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

10 files changed, 36 insertions, 24 deletions

diff --git a/src/corelib/kernel/qtimer.cpp b/src/corelib/kernel/qtimer.cpp
index 178227e914..948f697dc5 100644
--- a/src/corelib/kernel/qtimer.cpp
+++ b/src/corelib/kernel/qtimer.cpp
@@ -604,8 +604,8 @@ void QTimer::singleShot(int msec, Qt::TimerType timerType, const QObject *receiv
     \since 5.12
     \overload
 
-    Creates a connection from the timeout() signal to \a slot, and returns a
-    handle to the connection.
+    Creates a connection of type \a connectionType from the timeout() signal
+    to \a slot, and returns a handle to the connection.
 
     This method is provided for convenience.
     It's equivalent to calling \c {QObject::connect(timer, &QTimer::timeout, timer, slot, connectionType)}.
diff --git a/src/corelib/statemachine/qstatemachine.cpp b/src/corelib/statemachine/qstatemachine.cpp
index 3a86d971e2..945e36968f 100644
--- a/src/corelib/statemachine/qstatemachine.cpp
+++ b/src/corelib/statemachine/qstatemachine.cpp
@@ -2538,6 +2538,10 @@ QStateMachine::~QStateMachine()
            state machine. Commonly, this could mean that one of the states has not been given
            any parent or added to any machine. The context of this error is the source state of
            the transition.
+    \value StateMachineChildModeSetToParallelError The machine's \l childMode
+           property was set to \l{QState::ParallelStates}. This is illegal.
+           Only states may be declared as parallel, not the state machine
+           itself. This enum value was added in Qt 5.14.
 
     \sa setErrorState()
 */
diff --git a/src/corelib/time/qcalendar.cpp b/src/corelib/time/qcalendar.cpp
index b569a6834c..6e68a43a22 100644
--- a/src/corelib/time/qcalendar.cpp
+++ b/src/corelib/time/qcalendar.cpp
@@ -136,6 +136,7 @@ Q_GLOBAL_STATIC(Registry, calendarRegistry);
 
     \class QCalendarBackend
     \inmodule QtCore
+    \internal
     \reentrant
     \brief The QCalendarBackend class provides basic calendaring functions.
 
@@ -167,7 +168,7 @@ Q_GLOBAL_STATIC(Registry, calendarRegistry);
 */
 
 /*!
-    Constructs the calendar and registers it.
+    Constructs the calendar and registers it under \a name using \a id.
 */
 QCalendarBackend::QCalendarBackend(const QString &name, QCalendar::System id)
 {
@@ -192,7 +193,7 @@ QCalendarBackend::~QCalendarBackend()
     return the member of that enum that produces it. Other calendars should
     return User.
 
-    \sa QCalendar::fromEnum()
+    \sa QCalendarBackend::fromEnum()
 */
 QCalendar::System QCalendarBackend::calendarSystem() const
 {
@@ -391,7 +392,7 @@ int QCalendarBackend::maxMonthsInYear() const
 // Julian day number calculations
 
 /*!
-    \fn bool dateToJulianDay(int year, int month, int day, qint64 *jd) const
+    \fn bool QCalendarBackend::dateToJulianDay(int year, int month, int day, qint64 *jd) const
 
     Computes the Julian day number corresponding to the specified \a year, \a
     month, and \a day. Returns true and sets \a jd if there is such a date in
@@ -401,7 +402,7 @@ int QCalendarBackend::maxMonthsInYear() const
 */
 
 /*!
-    \fn QCalendar::YearMonthDay julianDayToDate(qint64 jd) const
+    \fn QCalendar::YearMonthDay QCalendarBackend::julianDayToDate(qint64 jd) const
 
     Computes the year, month, and day in this calendar for the given Julian day
     number \a jd. If the given day falls outside this calendar's scope
@@ -413,7 +414,7 @@ int QCalendarBackend::maxMonthsInYear() const
 */
 
 /*!
-   Returns the day of the week for a given Julian Day Number.
+   Returns the day of the week for the given Julian Day Number \a jd.
 
    This is 1 for Monday through 7 for Sunday.
 
@@ -541,7 +542,7 @@ int QCalendarBackend::dayOfWeek(qint64 jd) const
     QCalendarBackend sub-class must be registered before being exposed to Date
     and Time APIs.
 
-    \sa registerCalendar(), fromName()
+    \sa registerAlias(), fromName()
 */
 QStringList QCalendarBackend::availableCalendars()
 {
@@ -578,7 +579,7 @@ bool QCalendarBackend::registerAlias(const QString &name)
   other means. However, calendars available via the QCalendar::System enum are
   always registered when this is called.
 
-  \sa availableCalendars(), registerCalendar(), fromEnum()
+  \sa availableCalendars(), registerAlias(), fromEnum()
 */
 const QCalendarBackend *QCalendarBackend::fromName(QStringView name)
 {
@@ -662,7 +663,7 @@ const QCalendarBackend *QCalendarBackend::fromEnum(QCalendar::System system)
 
   A QCalendar value is immutable.
 
-  \sa QCalendarBackend, QDate, QDateTime
+  \sa QDate, QDateTime
 */
 
 /*!
@@ -675,6 +676,8 @@ const QCalendarBackend *QCalendarBackend::fromEnum(QCalendar::System system)
     \value Milankovic A revised Julian calendar used by some Orthodox churches.
     \value Jalali The Solar Hijri calendar (also called Persian).
     \value IslamicCivil The (tabular) Islamic Civil calendar.
+    \omitvalue Last
+    \omitvalue User
 
     \sa QCalendar
 */
@@ -772,7 +775,7 @@ bool QCalendar::isGregorian() const
 }
 
 /*!
-  Returns \c true if the given year is a leap year.
+  Returns \c true if the given \a year is a leap year.
 
   Since the year is not a whole number of days long, some years are longer than
   others. The difference may be a whole month or just a single day; the details
@@ -896,7 +899,7 @@ int QCalendar::maxMonthsInYear() const
 
 /*!
     \fn QDate QCalendar::dateFromParts(int year, int month, int day) const
-    \fn QDate QCalendar::dateFromParts(QCalendar::YearMonthDay parts) const
+    \fn QDate QCalendar::dateFromParts(const QCalendar::YearMonthDay &parts) const
 
     Converts a year, month, and day to a QDate.
 
@@ -924,7 +927,7 @@ QDate QCalendar::dateFromParts(const QCalendar::YearMonthDay &parts) const
     Converts a QDate to a year, month, and day of the month.
 
     The returned structure's isValid() shall be false if the calendar is unable
-    to represent the given \a date. Otherwise its \a year, \a month, and \a day
+    to represent the given \a date. Otherwise its year, month, and day
     members record the so-named parts of its representation.
 
     \sa dateFromParts(), isProleptic(), hasYearZero()
@@ -967,7 +970,7 @@ int QCalendar::dayOfWeek(QDate date) const
   in the specified \a locale; the \a format determines how fully it shall be
   expressed (i.e. to what extent it is abbreviated).
 
-  \sa standaloneMonthName(), maxMonthsInYear(), dateTimeString()
+  \sa standaloneMonthName(), maxMonthsInYear(), dateTimeToString()
 */
 QString QCalendar::monthName(const QLocale &locale, int month, int year,
                              QLocale::FormatType format) const
@@ -996,7 +999,7 @@ QString QCalendar::monthName(const QLocale &locale, int month, int year,
   specified \a locale; the \a format determines how fully it shall be expressed
   (i.e. to what extent it is abbreviated).
 
-  \sa monthName(), maxMonthsInYear(), dateTimeString()
+  \sa monthName(), maxMonthsInYear(), dateTimeToString()
 */
 QString QCalendar::standaloneMonthName(const QLocale &locale, int month, int year,
                                        QLocale::FormatType format) const
diff --git a/src/corelib/time/qcalendar.h b/src/corelib/time/qcalendar.h
index b117f4d6a9..594ea760a6 100644
--- a/src/corelib/time/qcalendar.h
+++ b/src/corelib/time/qcalendar.h
@@ -128,7 +128,7 @@ public:
         User = -1
     };
     // New entries must be added to the \enum doc in qcalendar.cpp and
-    // handled in QCalendar::fromEnum()
+    // handled in QCalendarBackend::fromEnum()
     Q_ENUM(System)
 
     explicit QCalendar(); // Gregorian, optimised
diff --git a/src/corelib/time/qdatetime.cpp b/src/corelib/time/qdatetime.cpp
index a9fc47e053..8b1665e7dd 100644
--- a/src/corelib/time/qdatetime.cpp
+++ b/src/corelib/time/qdatetime.cpp
@@ -1465,7 +1465,7 @@ QDate QDate::addMonths(int nmonths, QCalendar cal) const
 }
 
 /*!
-  \override
+  \overload
 */
 
 QDate QDate::addMonths(int nmonths) const
@@ -1530,7 +1530,7 @@ QDate QDate::addYears(int nyears, QCalendar cal) const
 }
 
 /*!
-  \override
+    \overload
 */
 
 QDate QDate::addYears(int nyears) const
diff --git a/src/corelib/time/qgregoriancalendar.cpp b/src/corelib/time/qgregoriancalendar.cpp
index 447185d124..633b1ea94e 100644
--- a/src/corelib/time/qgregoriancalendar.cpp
+++ b/src/corelib/time/qgregoriancalendar.cpp
@@ -57,7 +57,7 @@ using namespace QRoundingDown;
     The Gregorian calendar is a refinement of the earlier Julian calendar,
     itself a late form of the Roman calendar. It is widely used.
 
-    \sa QRomanCalendar, QJulianCalendar, QCalendarBackend, QCalendar
+    \sa QRomanCalendar, QJulianCalendar, QCalendar
 */
 
 QGregorianCalendar::QGregorianCalendar()
diff --git a/src/gui/rhi/qshader.cpp b/src/gui/rhi/qshader.cpp
index 72ce53c87a..6a2c596557 100644
--- a/src/gui/rhi/qshader.cpp
+++ b/src/gui/rhi/qshader.cpp
@@ -450,7 +450,7 @@ QShaderKey::QShaderKey(QShader::Source s,
 }
 
 /*!
-    Returns \c true if the two QShader objects \a a and \a b are equal,
+    Returns \c true if the two QShader objects \a lhs and \a rhs are equal,
     meaning they are for the same stage with matching sets of shader source or
     binary code.
 
@@ -486,7 +486,7 @@ uint qHash(const QShader &s, uint seed) Q_DECL_NOTHROW
 }
 
 /*!
-    Returns \c true if the two QShaderVersion objects \a a and \a b are
+    Returns \c true if the two QShaderVersion objects \a lhs and \a rhs are
     equal.
 
     \relates QShaderVersion
@@ -506,7 +506,7 @@ bool operator==(const QShaderVersion &lhs, const QShaderVersion &rhs) Q_DECL_NOT
  */
 
 /*!
-    Returns \c true if the two QShaderKey objects \a a and \a b are equal.
+    Returns \c true if the two QShaderKey objects \a lhs and \a rhs are equal.
 
     \relates QShaderKey
  */
@@ -536,7 +536,7 @@ uint qHash(const QShaderKey &k, uint seed) Q_DECL_NOTHROW
 }
 
 /*!
-    Returns \c true if the two QShaderCode objects \a a and \a b are equal.
+    Returns \c true if the two QShaderCode objects \a lhs and \a rhs are equal.
 
     \relates QShaderCode
  */
diff --git a/src/network/kernel/qhostinfo.cpp b/src/network/kernel/qhostinfo.cpp
index 9ce2d72bd3..f9335c3bb9 100644
--- a/src/network/kernel/qhostinfo.cpp
+++ b/src/network/kernel/qhostinfo.cpp
@@ -595,7 +595,9 @@ QHostInfo::QHostInfo(const QHostInfo &other)
 }
 
 /*!
-    Move-constucts a new QHostInfo from \a other.
+    \fn QHostInfo(QHostInfo &&other)
+
+    Move-constructs a new QHostInfo from \a other.
 
     \note The moved-from object \a other is placed in a
     partially-formed state, in which the only valid operations are
diff --git a/src/network/ssl/qsslsocket_qt.cpp b/src/network/ssl/qsslsocket_qt.cpp
index b0fb60ea76..9ff9a66c05 100644
--- a/src/network/ssl/qsslsocket_qt.cpp
+++ b/src/network/ssl/qsslsocket_qt.cpp
@@ -72,6 +72,7 @@ static QAsn1Element _q_PKCS7_data(const QByteArray &data)
 
     Some test vectors:
     http://www.drh-consultancy.demon.co.uk/test.txt
+    \internal
 */
 static QByteArray _q_PKCS12_keygen(char id, const QByteArray &salt, const QString &passPhrase, int n, int r)
 {
diff --git a/src/widgets/kernel/qwidgetrepaintmanager.cpp b/src/widgets/kernel/qwidgetrepaintmanager.cpp
index 4eb298e108..c3211e275f 100644
--- a/src/widgets/kernel/qwidgetrepaintmanager.cpp
+++ b/src/widgets/kernel/qwidgetrepaintmanager.cpp
@@ -147,6 +147,7 @@ QWidgetRepaintManager::~QWidgetRepaintManager()
 }
 
 /*!
+    \internal
     Invalidates the \a r (in widget's coordinates) of the backing store, i.e.
     all widgets intersecting with the region will be repainted when the backing
     store is synced.
@@ -193,6 +194,7 @@ static inline QRect widgetRectFor(QWidget *, const QRect &r) { return r; }
 static inline QRect widgetRectFor(QWidget *widget, const QRegion &) { return widget->rect(); }
 
 /*!
+    \internal
     Marks the region of the widget as dirty (if not already marked as dirty) and
     posts an UpdateRequest event to the top-level widget (if not already posted).