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

QDoc: extend "\include" usage model to "\overload"s

    XMLWordPrintable

Details

    • Suggestion
    • Resolution: Unresolved
    • P3: Somewhat important
    • None
    • None
    • Build tools: qdoc
    • None

    Description

      It would be great if \include-ed text paragraphs would also be auto-added to function overloads (marked with \overload).

      There are, obviously, certain pitfalls / exceptions:

      • If \include contains argument (marked with \a) and overload does not have this argument, such auto-include is somewhat useless (although, such things are not generalized to be \include-d in the first place, I guess)
      • There are very simple overloads that only contain \overload statement and that's it. For these, auto-include does not give much, the user is natively expected to see the descriptive version of a function. Let's call such documented functions "empty"

      For me, as a user, QDoc is a complete black-box, so the following logic is just how a user would see it (no clue if certain stuff is possible to achieve at all or not):
      1) It would be great if trivial (but not "empty") \overload-s would support auto-inclusion feature
      2) for anything non-trivial, reporting a warning (e.g. "auto-inclusion is not possible") or anything similar is good enough, I guess
      3) "empty" overloads are just ignored (see reasoning above)

      Attachments

        No reviews matched the request. Check your Options in the drop-down menu of this sections header.

        Activity

          People

            docinfrastructure Documentation Infrastructure Team
            agolubev Andrei Golubev
            Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

              Created:
              Updated:

              Gerrit Reviews

                There are no open Gerrit changes