> On 28 Apr 2017, at 09:35, Marc Mutz <[email protected]> wrote: > > Hi. > > TL;DR: I propose to document overloaded functions with a single comment block, > containing multiple \fn's and a common documentation text, to be rendered as > one documentation block preceded by a listing of all the \fn's, instead of as > individual functions. > > Since I learned that a qdoc comment block can contain multiple \fn statements, > I have tried to use it to document overloads with less duplication. E.g.: > > /*! > \fn bool QStringView::startsWith(QStringView str, Qt::CaseSensitivity cs) > const > \fn bool QStringView::startsWith(QLatin1String l1, Qt::CaseSensitivity cs) > const > \fn bool QStringView::startsWith(QChar ch) const > \fn bool QStringView::startsWith(QChar ch, Qt::CaseSensitivity cs) const > > Returns \c true if this string-view starts 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 endsWith(), qStartsWith() > */ > > instead of > > /*! > \fn bool QStringView::startsWith(QStringView str, Qt::CaseSensitivity cs) > const > > Returns \c true if this string-view starts with string-view \a str; > otherwise returns \c false. > > If \a cs is Qt::CaseSensitive (the default), the search is case-sensitive; > otherwise the search is case-insensitive. > > \sa endsWith(), qStartsWith() > */ > > /*! > \fn bool QStringView::startsWith(QLatin1String l1, Qt::CaseSensitivity cs) > const > > Returns \c true if this string-view starts with Latin-1 string \a l1; > otherwise returns \c false. > > If \a cs is Qt::CaseSensitive (the default), the search is case-sensitive; > otherwise the search is case-insensitive. > > \sa endsWith(), qStartsWith() > */ > > /*! > \fn bool QStringView::startsWith(QChar ch) const > > Returns \c true if this string-view starts with character \a ch; > otherwise returns \c false. > > The search is case-sensitive. > > \sa endsWith(), qStartsWith() > */ > > /*! > \fn bool QStringView::startsWith(QChar ch, Qt::CaseSensitivity cs) const > > Returns \c true if this string-view starts with character \a ch; > otherwise returns \c false. > > If \a cs is Qt::CaseSensitive, the search is case-sensitive; > otherwise the search is case-insensitive. > > \sa endsWith(), qStartsWith() > */ > > And that's just startsWith(). QString::contains() current has 8, > QString::arg() has 14, not counting the 8 additional multi-arg() overloads. > > Each of them contains mostly the same text. It's a long time since I had to > consult QString documentation, but I guess for users, this is as hard to read > as it is for us to write. Sure. cut-n-paste gives you fast initial results. > But fear the day when you have to make a change to all of the contains() > documentation blocks, and be it just for adding a missing hyphen. > > So, I hear you say, if qdoc already supports multiple \fn in one comment > block, why don't you just use it. > > This is where http://bugreports.qt.io/browse/QTBUG-60420 comes in. > > Currently, any content in a multi-\fn block pertains to all functions > designated by an included \fn, with no way to change. The initial example, > e.g., copies the text, which is clearly written to refer to the overload set, > not any particular funciton, verbatim for each of the four functions. As a > consequence of this, it also throws warnings about invalid \a references. > > So, name the parameters the same in every overload... > > That works as long as all overloads were added in the same Qt release, > because, as I said, all content, and thus \since, pertains to all \fn's. IOW: > you cannot represent the fact that one overload was added in a later Qt > version. > > What I would like to see is something more akin to the presentation in > cppreference.com. Before you shout: no, I don't like the numbered listing of > all overloads followed dumbly by a numbered listing of documentation for each > overload. What I like is the numbered listing of the overloads, followed by > free-form text, as in the initial example. It's up to the individual > documentation writer and his reviewers to avoid falling into a > cppreference.com-style of itemised text. I think that the initial example is > an elegant way of how to document that particular set of overloads without > having to refer to any of them in particular. > > I would like to see a multi-\fn comment block (and only those) transformed > into a multi-function block in the documentation, too, first listing all the > functions designated by the \fn's, with \since, \obsolete, ... attached to a > function (like in cppreference.com, following the signature, in parentheses), > not the whole block, followed by the free-form block. > > Naturally, there'd need to be a way to reference any particular overload. This > could be done with a \label added to each function, or just a number: \1, \2, > referring to their position in the listing of \fn's. > > This would probably shrink the length of the QString and QStringView page by > more than half, and, if we would add \until into the mix, would allow to > represent even complicated cases like QSharedPointer::create() very naturally: > > > \fn QSharedPointer::create() > \since 5.1 > \until 5.7 > \fn QSharedPointer::create(const Arg &arg) > \since 5.4 > \until 5.7 > \fn QSharedPointer::create(Args &&...args) > \since 5.4 > > <docs> > > Overload \3 requires C++11, which used to be optional. When Qt made support > for C++11 a requirement in 5.7, overloads \1 and \2 were dropped, since \3 > can represent them. > > Rendered as: > > 1. QSharedPointer<T> QSharedPointer::create() [static] (since > 5.1) > (until 5.7) > 2. QSharedPointer<T> QSharedPointer::create(const Arg &arg) [static] (since > 5.4) > (until 5.7) > 3. QSharedPointer<T> QSharedPointer::create(const Arg &arg) [static] (since > 5.4) > > <docs> > > Overload (3) requires ... > > What do you think? > > Thanks, > Marc > > -- > Marc Mutz <[email protected]> | Senior Software Engineer > KDAB (Deutschland) GmbH & Co.KG, a KDAB Group Company > Tel: +49-30-521325470 > KDAB - The Qt, C++ and OpenGL Experts > _______________________________________________ > Development mailing list > [email protected] > http://lists.qt-project.org/mailman/listinfo/development
Hi, +1 I think it’s a pretty good idea. That will make the documentation more concise which isn’t a bad thing when looking for overloads. Samuel
signature.asc
Description: Message signed with OpenPGP
_______________________________________________ Development mailing list [email protected] http://lists.qt-project.org/mailman/listinfo/development
