-
Bug
-
Resolution: Unresolved
-
P2: Important
-
None
-
6.11
-
-
DaVinci 125, DaVinci 126
In fixing QTBUG-140485 I initially followed the documentation (link is to snapshot so may change) of \overload, which said that I should mark the primary in an overload family with \overload primary and included "the function name plus '()' as a parameter to the \overload command" (as per the documentation) on the others.
(This lead to warning about the overloads' parameters being undocumented; see QTBUG-140508.)
This, however, generated docs in which the overloads just said, to take the example I was primarily asked to fix,
This function overloads QDate::startOfDay().
which, as documentation of QDate::startOfDay() const was rather less than helpful. It might have been more helpful had QDate::startOfDay() appeared in it as a link to QDate::startOfDay(const QTimeZone &zone) const, but it did not. Fortunately the one improvement I did get out of this change was that now this doc appeared immediately before the primary, which was thus visible directly below it (assuming the reader thinks to look), an improvement on previously where it had appeared after, so following the link to it had left the primary just out of sight above the top of the browser's view of the page.
The docs of \overload clearly state (amending some double-backslash issues paulwicking is fixing, that also upset Jira's formatting) that
For parameterless targets like \overload functionName(), QDoc searches for a link target in this order:
- The function explicitly marked with \overload primary, if one exists.
- The parameterless overload of that function, if one exists.
- The overload QDoc determines to be primary based on its sorting rules.
It would seem that the first step in that is failing, as I did add \overload primary to the primary overload in each case. It is possible to work around this issue by giving the actual signature of the primary, but this is tedious and error-prone.
The bug I'm reporting here is that failure to link to the function explicitly linked with \overload primary in each case.
- relates to
-
QTBUG-140508 QDoc complains about undocumented parameters to \overload fn()
-
- In Review
-
-
QTBUG-140485 Missing documentation for QDate::startOfDay
-
- In Review
-
For Gerrit Dashboard: QTBUG-140510 | ||||||
---|---|---|---|---|---|---|
# | Subject | Branch | Project | Status | CR | V |
679741,3 | QDoc: Make \overload primary work end to end | dev | qt/qttools | Status: NEW | 0 | 0 |
679742,4 | QDoc: Revamp \overload documentation | dev | qt/qttools | Status: NEW | +2 | 0 |
679743,4 | QDoc: Extract \overload command processing | dev | qt/qttools | Status: NEW | 0 | 0 |