Uploaded image for project: 'Qt'
  1. Qt
  2. QTBUG-60420

qdoc: Better support for multi-\fn documentation blocks

    XMLWordPrintable

Details

    • abb5dc62132afe52861b6923255ba84bf42dfbab

    Description

      Now that I learned that a documentation commit can contain multi \fn declarations, I don't want to go back to documenting each overload with a separate block.

      Here are some issue I've come across:

      • can't give per-\fn-\since
      • qdoc warns when \a references resolve to a parameter in any of the \fn, but not all

      As for presentation, I'd really like to see us move to a cppreference.com-style presentation. A simple, opt-in, way to do this is to treat multi-\fn blocks as one documentation entry. This is what I expected to happen when in a change I wrote:

      /*!
          \fn bool QStringView::endsWith(QStringView str, Qt::CaseSensitivity cs) const
          \fn bool QStringView::endsWith(QLatin1String l1, Qt::CaseSensitivity cs) const
          \fn bool QStringView::endsWith(QChar ch) const
          \fn bool QStringView::endsWith(QChar ch, Qt::CaseSensitivity cs) const
      
          Returns \c true if this string-view ends 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 startsWith(), qEndsWith()
      */
      

      This gets expanded to four identical documentation blocks in the html output. I think it should stay one block, which first lists all the function signatures (with since XX) in parentheses, then the documentation as written. The order of overloads should stay as the order of \fns in the source.

      The next step would be to number the overloads numerically in the output, and add a way to reference a particular overload, resolving in the output to the number assigned to it in the output, and to add an \until that would just be output the same as \since, in parentheses after the overload signature.

      Cf. the presentation of the std::string::append overloads in http://en.cppreference.com/w/cpp/string/basic_string/append with our presentation in http://doc.qt.io/qt-5/qstring.html#append

      Attachments

        For Gerrit Dashboard: QTBUG-60420
        # Subject Branch Project Status CR V

        Activity

          People

            gbk Martin Smith (Qt)
            mmutz Marc Mutz
            Votes:
            0 Vote for this issue
            Watchers:
            6 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved:

              Gerrit Reviews

                There are no open Gerrit changes