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

[Martin Smith]

>I am a bit worried about having a good way to describe the specifics of a >specific overload or group thereof.

Remember you will still have the option of giving an overload its own qdoc comment instead of including it in the common \fn comment.

martin
________________________________________
From: Development <development-bounces+martin.smith=qt.io at qt-project.org> on behalf of André Somers <andre at familiesomers.nl>
Sent: Friday, April 28, 2017 3:19:14 PM
To: development at qt-project.org
Subject: Re: [Development] [docs] changing the way overloads are documented and presented

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
   ...
   \fnendgroup
   \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
   \fnendgroup
   \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
   ...
   \endgroup

    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.
    (...)
    \endgroupdoc

    \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.

André