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

[Marc Mutz]

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