[Development] [docs] changing the way overloads are documented and presented

[Samuel Gaist]

> On 28 Apr 2017, at 09:35, Marc Mutz <marc.mutz at kdab.com> 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 <marc.mutz at kdab.com> | 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
> Development at qt-project.org
> 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 801 bytes
Desc: Message signed with OpenPGP
URL: <http://lists.qt-project.org/pipermail/development/attachments/20170428/b358e3d2/attachment.sig>