Details
-
Bug
-
Resolution: Done
-
P3: Somewhat important
-
5.10
-
None
-
abb5dc62132afe52861b6923255ba84bf42dfbab
Description
Now that I learned that a documentation commit can contain multi \fn declarations, I don't want to go back to documenting each overload with a separate block.
Here are some issue I've come across:
- can't give per-\fn-\since
- qdoc warns when \a references resolve to a parameter in any of the \fn, but not all
As for presentation, I'd really like to see us move to a cppreference.com-style presentation. A simple, opt-in, way to do this is to treat multi-\fn blocks as one documentation entry. This is what I expected to happen when in a change I wrote:
/*! \fn bool QStringView::endsWith(QStringView str, Qt::CaseSensitivity cs) const \fn bool QStringView::endsWith(QLatin1String l1, Qt::CaseSensitivity cs) const \fn bool QStringView::endsWith(QChar ch) const \fn bool QStringView::endsWith(QChar ch, Qt::CaseSensitivity cs) const Returns \c true if this string-view ends with string-view \a str, Latin-1 string \a l1, or character \a ch, respectively; otherwise returns \c false. If \a cs is Qt::CaseSensitive (the default), the search is case-sensitive; otherwise the search is case-insensitive. \sa startsWith(), qEndsWith() */
This gets expanded to four identical documentation blocks in the html output. I think it should stay one block, which first lists all the function signatures (with since XX) in parentheses, then the documentation as written. The order of overloads should stay as the order of \fns in the source.
The next step would be to number the overloads numerically in the output, and add a way to reference a particular overload, resolving in the output to the number assigned to it in the output, and to add an \until that would just be output the same as \since, in parentheses after the overload signature.
Cf. the presentation of the std::string::append overloads in http://en.cppreference.com/w/cpp/string/basic_string/append with our presentation in http://doc.qt.io/qt-5/qstring.html#append