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

André Somers andre at familiesomers.nl
Fri Apr 28 15:19:14 CEST 2017

Op 28/04/2017 om 09:35 schreef 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.
Generally, I like the idea. Thank you for that suggestion! It would
really clean up the docs for some classes, and make it easier to find
perhaps more suitable overloads for your case. Do you also propose to
use it to group related functions instead of mere overloads, like again
cppreference is doing for its standard algorithms (ie.
find/find_if/find_if_not  and any_of/all_of/none_of)?

However, I am a bit worried about having a good way to describe the
specifics of a specific overload or group thereof. Having that all in
running text will lead to situations where such information is harder to
find and takes more time to read through than it currently does. To go
back to your QString::arg example, I do not want to have to do a text
analysis of the docs belonging to 22 overloads to just get around how to
use _one_ of these. Then again, many of the overloads are very similar.

Perhaps we could have some form of grouping within such blocks (where
groups of functions may  be of size 1) to allow more specific docs for
such groups with an easy link to them? Taking the QString::arg
overloads, you'd probably get 2 or 3 groups:
1: the overloads taking a single value argument
1a: the overloads taking a numeric value argument
1b: the overloads taking a string or QChar
2: the overloads taking multiple QStrings

You might get something like:

    \fngroup numeric Numeric single value overloads
    \fn QString::arg(qulonglong a, int fieldWidth = 0, int base = 10,
QChar fillChar = QLatin1Char( ' ' )) const
    \fn QString::arg(long a, int fieldWidth = 0, int base = 10, QChar
fillChar = QLatin1Char( ' ' )) const
    \fn QString::arg(int a, int fieldWidth = 0, int base = 10, QChar
fillChar = QLatin1Char( ' ' )) const
   \fngroup other Other single value overloads
   \fn QString::arg(const QString &a, int fieldWidth = 0, QChar fillChar
= QLatin1Char( ' ' )) const
   \fn QString::arg(QChar a, int fieldWidth = 0, QChar fillChar =
QLatin1Char( ' ' )) const
   \fngroup multi Multi-value overloads
   \fn QString::arg(const QString &a1, const QString &a2) const
   \fn QString::arg(const QString &a1, const QString &a2, const QString
&a3) const

    Returns a copy of this string with the lowest numbered place marker
replaced by string a, i.e., %1, %2, ..., %99.

    \groupdoc numeric
    fieldWidth specifies the minimum amount of space that a is padded to
and filled with the character fillChar. A
    positive value produces right-aligned text; a negative value
produces left-aligned text.

    \groupdoc other
    \groupdoc other
    \groupdoc multi
    This is functionaly the same as str.arg(a1).arg(a2), except that the
argument strings are replaced in one pass. This is faster, and it can
make a difference if a1 contains e.g. %1: (...)
    \groupdoc multi

Which, I image, would render as a list like Marc described, only grouped
as indicated with the different groups directly linking to the right
contents block. That contents block could then again indicate the name
of the group and perhaps which overloads are part of that.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20170428/91cacf3a/attachment.html>

More information about the Development mailing list