>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 <[email protected]> on behalf of André Somers <[email protected]> Sent: Friday, April 28, 2017 3:19:14 PM To: [email protected] 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é _______________________________________________ Development mailing list [email protected] http://lists.qt-project.org/mailman/listinfo/development
